PGdoc: add missing ID attribute to create_subscription.sgml

From f1bb1fc7c978036f1de9059185d46c20dcb45896 Mon Sep 17 00:00:00 2001
From: Hayato Kuroda <kuroda.hayato@fujitsu.com>
Date: Wed, 22 Mar 2023 10:14:22 +0000
Subject: [PATCH v2 1/2] Add XML ID attributes to create_subscription.sgml

In commit ecb696, an XML ID attribute was added to only one varlistentry,
creating inconsistency with the commit 78ee60. This commit adds XML ID
attributes to all varlistentries in create_subscritpion.sgml for consistency.
Additionally, links are added to refer subscription options, enhancing the
readability of documents.
---
 doc/src/sgml/config.sgml                  |  4 +--
 doc/src/sgml/logical-replication.sgml     | 19 +++++++-------
 doc/src/sgml/ref/alter_subscription.sgml  | 30 ++++++++++++-----------
 doc/src/sgml/ref/create_subscription.sgml | 30 +++++++++++------------
 doc/src/sgml/ref/pg_dump.sgml             |  6 ++---
 5 files changed, 46 insertions(+), 43 deletions(-)

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 481f93cea1..eab3429d05 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -11722,8 +11722,8 @@ LOG:  CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1)
         On the publisher side, <varname>logical_replication_mode</varname>
         allows streaming or serializing changes immediately in logical decoding.
         When set to <literal>immediate</literal>, stream each change if the
-        <literal>streaming</literal> option (see optional parameters set by
-        <link linkend="sql-createsubscription"><command>CREATE SUBSCRIPTION</command></link>)
+        <link linkend="sql-createsubscription-with-streaming"><literal>streaming</literal></link>
+        parameter of <link linkend="sql-createsubscription"><command>CREATE SUBSCRIPTION</command></link>
         is enabled, otherwise, serialize each change.  When set to
         <literal>buffered</literal>, the decoding will stream or serialize
         changes when <varname>logical_decoding_work_mem</varname> is reached.
diff --git a/doc/src/sgml/logical-replication.sgml b/doc/src/sgml/logical-replication.sgml
index 3836d13ad3..4aa643ce94 100644
--- a/doc/src/sgml/logical-replication.sgml
+++ b/doc/src/sgml/logical-replication.sgml
@@ -252,8 +252,8 @@
    additional columns not provided by the published table.  Any such columns
    will be filled with the default value as specified in the definition of the
    target table. However, logical replication in binary format is more
-   restrictive. See the <link linkend="sql-createsubscription-binary"><literal>binary</literal>
-   option</link> of <command>CREATE SUBSCRIPTION</command> for details.
+   restrictive. See the <link linkend="sql-createsubscription-with-binary"><literal>binary</literal></link>
+   option of <command>CREATE SUBSCRIPTION</command> for details.
   </para>
 
   <sect2 id="logical-replication-subscription-slot">
@@ -587,7 +587,8 @@ ALTER SUBSCRIPTION
 
    <para>
     Example 2: Where the subscription says <literal>connect = false</literal>,
-    but also specifies the <literal>slot_name</literal>
+    but also specifies the <link linkend="sql-createsubscription-with-slot-name"><literal>slot_name</literal></link>
+    option.
     <itemizedlist>
      <listitem>
       <para>
@@ -704,9 +705,9 @@ ALTER SUBSCRIPTION
     If the row filter evaluates to <literal>false</literal> or <literal>NULL</literal>
     then the row is not replicated. The <literal>WHERE</literal> clause expression
     is evaluated with the same role used for the replication connection (i.e.
-    the role specified in the <literal>CONNECTION</literal> clause of the
-    <xref linkend="sql-createsubscription"/>). Row filters have no effect for
-    <command>TRUNCATE</command> command.
+    the role specified in the <link linkend="sql-createsubscription-connection"><literal>CONNECTION</literal></link>
+    clause of the <xref linkend="sql-createsubscription"/>). Row filters have
+    no effect for <command>TRUNCATE</command> command.
    </para>
 
   </sect2>
@@ -1500,9 +1501,9 @@ CONTEXT:  processing remote data for replication origin "pg_16395" during "INSER
    <function>pg_replication_origin_advance()</function></link> function.
    Before using this function, the subscription needs to be disabled temporarily
    either by <command>ALTER SUBSCRIPTION ... DISABLE</command> or, the
-   subscription can be used with the <literal>disable_on_error</literal> option.
-   Then, you can use <function>pg_replication_origin_advance()</function> function
-   with the <parameter>node_name</parameter> (i.e., <literal>pg_16395</literal>)
+   subscription can be used with the <link linkend="sql-createsubscription-with-disable-on-error"><literal>disable_on_error</literal></link>
+   option. Then, you can use <function>pg_replication_origin_advance()</function>
+   function with the <parameter>node_name</parameter> (i.e., <literal>pg_16395</literal>)
    and the next LSN of the finish LSN (i.e., 0/14C0379).  The current position of
    origins can be seen in the <link linkend="view-pg-replication-origin-status">
    <structname>pg_replication_origin_status</structname></link> system view.
diff --git a/doc/src/sgml/ref/alter_subscription.sgml b/doc/src/sgml/ref/alter_subscription.sgml
index e92346edef..0fb35bdfb7 100644
--- a/doc/src/sgml/ref/alter_subscription.sgml
+++ b/doc/src/sgml/ref/alter_subscription.sgml
@@ -71,10 +71,10 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
    executed inside a transaction block.
 
    These commands also cannot be executed when the subscription has
-   <literal>two_phase</literal> commit enabled,
-   unless <literal>copy_data</literal> is <literal>false</literal>.
-   See column <structfield>subtwophasestate</structfield> of
-   <link linkend="catalog-pg-subscription"><structname>pg_subscription</structname></link>
+   <link linkend="sql-createsubscription-with-two-phase"><literal>two_phase</literal></link>
+   commit enabled, unless <link linkend="sql-createsubscription-with-copy-data"><literal>copy_data</literal></link>
+   is <literal>false</literal>. See column <structfield>subtwophasestate</structfield>
+   of <link linkend="catalog-pg-subscription"><structname>pg_subscription</structname></link>
    to know the actual two-phase state.
   </para>
  </refsect1>
@@ -175,12 +175,13 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
          <para>
           See <xref linkend="sql-createsubscription-notes"/> for details of
           how <literal>copy_data = true</literal> can interact with the
-          <literal>origin</literal> parameter.
+          <link linkend="sql-createsubscription-with-origin"><literal>origin</literal></link>
+          parameter.
          </para>
          <para>
-          See the <link linkend="sql-createsubscription-binary"><literal>binary</literal>
-          option</link> of <command>CREATE SUBSCRIPTION</command> for details
-          about copying pre-existing data in binary format.
+          See the <link linkend="sql-createsubscription-with-binary"><literal>binary</literal></link>
+          parameter of <command>CREATE SUBSCRIPTION</command> for details about
+          copying pre-existing data in binary format.
          </para>
         </listitem>
        </varlistentry>
@@ -214,12 +215,13 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
      <para>
       This clause alters parameters originally set by
       <xref linkend="sql-createsubscription"/>.  See there for more
-      information.  The parameters that can be altered
-      are <literal>slot_name</literal>,
-      <literal>synchronous_commit</literal>,
-      <literal>binary</literal>, <literal>streaming</literal>,
-      <literal>disable_on_error</literal>, and
-      <literal>origin</literal>.
+      information.  The parameters that can be altered are
+      <link linkend="sql-createsubscription-with-slot-name"><literal>slot_name</literal></link>,
+      <link linkend="sql-createsubscription-with-synchronous-commit"><literal>synchronous_commit</literal></link>,
+      <link linkend="sql-createsubscription-with-binary"><literal>binary</literal></link>,
+      <link linkend="sql-createsubscription-with-streaming"><literal>streaming</literal></link>,
+      <link linkend="sql-createsubscription-with-disable-on-error"><literal>disable_on_error</literal></link>,
+      and <link linkend="sql-createsubscription-with-origin"><literal>origin</literal></link>.
      </para>
     </listitem>
    </varlistentry>
diff --git a/doc/src/sgml/ref/create_subscription.sgml b/doc/src/sgml/ref/create_subscription.sgml
index 9d4b9d4e33..a66b8025f3 100644
--- a/doc/src/sgml/ref/create_subscription.sgml
+++ b/doc/src/sgml/ref/create_subscription.sgml
@@ -61,7 +61,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
   <title>Parameters</title>
 
   <variablelist>
-   <varlistentry>
+   <varlistentry id="sql-createsubscription-name">
     <term><replaceable class="parameter">subscription_name</replaceable></term>
     <listitem>
      <para>
@@ -70,7 +70,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
     </listitem>
    </varlistentry>
 
-   <varlistentry>
+   <varlistentry id="sql-createsubscription-connection">
     <term><literal>CONNECTION '<replaceable class="parameter">conninfo</replaceable>'</literal></term>
     <listitem>
      <para>
@@ -81,7 +81,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
     </listitem>
    </varlistentry>
 
-   <varlistentry>
+   <varlistentry id="sql-createsubscription-publication">
     <term><literal>PUBLICATION <replaceable class="parameter">publication_name</replaceable> [, ...]</literal></term>
     <listitem>
      <para>
@@ -90,7 +90,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
     </listitem>
    </varlistentry>
 
-   <varlistentry>
+   <varlistentry id="sql-createsubscription-with">
     <term><literal>WITH ( <replaceable class="parameter">subscription_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] )</literal></term>
     <listitem>
      <para>
@@ -102,7 +102,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
 
       <variablelist>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-connect">
         <term><literal>connect</literal> (<type>boolean</type>)</term>
         <listitem>
          <para>
@@ -129,7 +129,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-create-slot">
         <term><literal>create_slot</literal> (<type>boolean</type>)</term>
         <listitem>
          <para>
@@ -145,7 +145,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-enabled">
         <term><literal>enabled</literal> (<type>boolean</type>)</term>
         <listitem>
          <para>
@@ -156,7 +156,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-slot-name">
         <term><literal>slot_name</literal> (<type>string</type>)</term>
         <listitem>
          <para>
@@ -185,7 +185,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
 
       <variablelist>
 
-       <varlistentry id="sql-createsubscription-binary" xreflabel="binary">
+       <varlistentry id="sql-createsubscription-with-binary">
         <term><literal>binary</literal> (<type>boolean</type>)</term>
         <listitem>
          <para>
@@ -222,7 +222,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-copy-data">
         <term><literal>copy_data</literal> (<type>boolean</type>)</term>
         <listitem>
          <para>
@@ -243,7 +243,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-streaming">
         <term><literal>streaming</literal> (<type>enum</type>)</term>
         <listitem>
          <para>
@@ -271,7 +271,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-synchronous-commit">
         <term><literal>synchronous_commit</literal> (<type>enum</type>)</term>
         <listitem>
          <para>
@@ -303,7 +303,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-two-phase">
         <term><literal>two_phase</literal> (<type>boolean</type>)</term>
         <listitem>
          <para>
@@ -334,7 +334,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-disable-on-error">
         <term><literal>disable_on_error</literal> (<type>boolean</type>)</term>
         <listitem>
          <para>
@@ -346,7 +346,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-origin">
         <term><literal>origin</literal> (<type>string</type>)</term>
         <listitem>
          <para>
diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index d6b1faa804..77299878e0 100644
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -1458,9 +1458,9 @@ CREATE DATABASE foo WITH TEMPLATE template0;
    truncate the target tables before initiating a new full table copy.  If users
    intend to copy initial data during refresh they must create the slot with
    <literal>two_phase = false</literal>.  After the initial sync, the
-   <literal>two_phase</literal> option will be automatically enabled by the
-   subscriber if the subscription had been originally created with
-   <literal>two_phase = true</literal> option.
+   <link linkend="sql-createsubscription-with-two-phase"><literal>two_phase</literal></link>
+   option will be automatically enabled by the subscriber if the subscription
+   had been originally created with <literal>two_phase = true</literal> option.
   </para>
  </refsect1>
 
-- 
2.27.0

From 1f6ec019b5c9c9eebe1ba25043dfc7b4677d07d3 Mon Sep 17 00:00:00 2001
From: Hayato Kuroda <kuroda.hayato@fujitsu.com>
Date: Fri, 24 Mar 2023 11:00:53 +0000
Subject: [PATCH v2 2/2] Add XML ID attributes to create_publication.sgml

This commit adds XML ID attributes to all varlistentries in
create_publication.sgml. Additionally, links are included to refer to publication
options, making documents more readable.
---
 doc/src/sgml/logical-replication.sgml     | 27 +++++++++++++----------
 doc/src/sgml/ref/alter_publication.sgml   |  6 ++---
 doc/src/sgml/ref/create_publication.sgml  | 14 ++++++------
 doc/src/sgml/ref/create_subscription.sgml | 23 ++++++++++---------
 doc/src/sgml/system-views.sgml            |  6 ++---
 5 files changed, 40 insertions(+), 36 deletions(-)

diff --git a/doc/src/sgml/logical-replication.sgml b/doc/src/sgml/logical-replication.sgml
index 4aa643ce94..5f361bf641 100644
--- a/doc/src/sgml/logical-replication.sgml
+++ b/doc/src/sgml/logical-replication.sgml
@@ -798,11 +798,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>
@@ -826,10 +827,11 @@ 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
-     <xref linkend="logical-replication-snapshot"/>, and see
-     <xref linkend="logical-replication-subscription-examples"/> for examples.
+     <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>
    </warning>
 
@@ -860,15 +862,16 @@ 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>
diff --git a/doc/src/sgml/ref/alter_publication.sgml b/doc/src/sgml/ref/alter_publication.sgml
index cd20868bca..a37bb734b7 100644
--- a/doc/src/sgml/ref/alter_publication.sgml
+++ b/doc/src/sgml/ref/alter_publication.sgml
@@ -54,7 +54,7 @@ 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 +79,8 @@ 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
index a2946feaa3..1cea8b4563 100644
--- 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,7 +158,7 @@ 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>
@@ -166,7 +166,7 @@ CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
       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
index a66b8025f3..f4c62c5698 100644
--- a/doc/src/sgml/ref/create_subscription.sgml
+++ b/doc/src/sgml/ref/create_subscription.sgml
@@ -418,17 +418,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
-   <xref linkend="logical-replication-subscription-examples"/> for examples.
+   <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>
 
   <para>
diff --git a/doc/src/sgml/system-views.sgml b/doc/src/sgml/system-views.sgml
index 7c8fc3f654..a6e50dbadb 100644
--- a/doc/src/sgml/system-views.sgml
+++ b/doc/src/sgml/system-views.sgml
@@ -2145,9 +2145,9 @@ 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>
-- 
2.27.0

From e12d99576dde7d0aeb59f755f1ed51f06008c6a7 Mon Sep 17 00:00:00 2001
From: Hayato Kuroda <kuroda.hayato@fujitsu.com>
Date: Wed, 22 Mar 2023 10:14:22 +0000
Subject: [PATCH v3 1/2] Add XML ID attributes to create_subscription.sgml

In commit ecb696, an XML ID attribute was added to only one varlistentry,
creating inconsistency with the commit 78ee60. This commit adds XML ID
attributes to all varlistentries in create_subscription.sgml for consistency.
Additionally, links are added to refer to the subscription options, enhancing
the readability of documents.
---
 doc/src/sgml/config.sgml                  |  4 +--
 doc/src/sgml/logical-replication.sgml     | 19 +++++++------
 doc/src/sgml/ref/alter_subscription.sgml  | 34 ++++++++++++-----------
 doc/src/sgml/ref/create_subscription.sgml | 30 ++++++++++----------
 doc/src/sgml/ref/pg_dump.sgml             |  6 ++--
 5 files changed, 48 insertions(+), 45 deletions(-)

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 481f93cea1..a85bba0998 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -11722,8 +11722,8 @@ LOG:  CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1)
         On the publisher side, <varname>logical_replication_mode</varname>
         allows streaming or serializing changes immediately in logical decoding.
         When set to <literal>immediate</literal>, stream each change if the
-        <literal>streaming</literal> option (see optional parameters set by
-        <link linkend="sql-createsubscription"><command>CREATE SUBSCRIPTION</command></link>)
+        <link linkend="sql-createsubscription-with-streaming"><literal>streaming</literal></link>
+        option of <link linkend="sql-createsubscription"><command>CREATE SUBSCRIPTION</command></link>
         is enabled, otherwise, serialize each change.  When set to
         <literal>buffered</literal>, the decoding will stream or serialize
         changes when <varname>logical_decoding_work_mem</varname> is reached.
diff --git a/doc/src/sgml/logical-replication.sgml b/doc/src/sgml/logical-replication.sgml
index 3836d13ad3..4aa643ce94 100644
--- a/doc/src/sgml/logical-replication.sgml
+++ b/doc/src/sgml/logical-replication.sgml
@@ -252,8 +252,8 @@
    additional columns not provided by the published table.  Any such columns
    will be filled with the default value as specified in the definition of the
    target table. However, logical replication in binary format is more
-   restrictive. See the <link linkend="sql-createsubscription-binary"><literal>binary</literal>
-   option</link> of <command>CREATE SUBSCRIPTION</command> for details.
+   restrictive. See the <link linkend="sql-createsubscription-with-binary"><literal>binary</literal></link>
+   option of <command>CREATE SUBSCRIPTION</command> for details.
   </para>
 
   <sect2 id="logical-replication-subscription-slot">
@@ -587,7 +587,8 @@ ALTER SUBSCRIPTION
 
    <para>
     Example 2: Where the subscription says <literal>connect = false</literal>,
-    but also specifies the <literal>slot_name</literal>
+    but also specifies the <link linkend="sql-createsubscription-with-slot-name"><literal>slot_name</literal></link>
+    option.
     <itemizedlist>
      <listitem>
       <para>
@@ -704,9 +705,9 @@ ALTER SUBSCRIPTION
     If the row filter evaluates to <literal>false</literal> or <literal>NULL</literal>
     then the row is not replicated. The <literal>WHERE</literal> clause expression
     is evaluated with the same role used for the replication connection (i.e.
-    the role specified in the <literal>CONNECTION</literal> clause of the
-    <xref linkend="sql-createsubscription"/>). Row filters have no effect for
-    <command>TRUNCATE</command> command.
+    the role specified in the <link linkend="sql-createsubscription-connection"><literal>CONNECTION</literal></link>
+    clause of the <xref linkend="sql-createsubscription"/>). Row filters have
+    no effect for <command>TRUNCATE</command> command.
    </para>
 
   </sect2>
@@ -1500,9 +1501,9 @@ CONTEXT:  processing remote data for replication origin "pg_16395" during "INSER
    <function>pg_replication_origin_advance()</function></link> function.
    Before using this function, the subscription needs to be disabled temporarily
    either by <command>ALTER SUBSCRIPTION ... DISABLE</command> or, the
-   subscription can be used with the <literal>disable_on_error</literal> option.
-   Then, you can use <function>pg_replication_origin_advance()</function> function
-   with the <parameter>node_name</parameter> (i.e., <literal>pg_16395</literal>)
+   subscription can be used with the <link linkend="sql-createsubscription-with-disable-on-error"><literal>disable_on_error</literal></link>
+   option. Then, you can use <function>pg_replication_origin_advance()</function>
+   function with the <parameter>node_name</parameter> (i.e., <literal>pg_16395</literal>)
    and the next LSN of the finish LSN (i.e., 0/14C0379).  The current position of
    origins can be seen in the <link linkend="view-pg-replication-origin-status">
    <structname>pg_replication_origin_status</structname></link> system view.
diff --git a/doc/src/sgml/ref/alter_subscription.sgml b/doc/src/sgml/ref/alter_subscription.sgml
index e92346edef..b7e6d2e83a 100644
--- a/doc/src/sgml/ref/alter_subscription.sgml
+++ b/doc/src/sgml/ref/alter_subscription.sgml
@@ -71,10 +71,10 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
    executed inside a transaction block.
 
    These commands also cannot be executed when the subscription has
-   <literal>two_phase</literal> commit enabled,
-   unless <literal>copy_data</literal> is <literal>false</literal>.
-   See column <structfield>subtwophasestate</structfield> of
-   <link linkend="catalog-pg-subscription"><structname>pg_subscription</structname></link>
+   <link linkend="sql-createsubscription-with-two-phase"><literal>two_phase</literal></link>
+   commit enabled, unless <link linkend="sql-createsubscription-with-copy-data"><literal>copy_data</literal></link>
+   is <literal>false</literal>. See column <structfield>subtwophasestate</structfield>
+   of <link linkend="catalog-pg-subscription"><structname>pg_subscription</structname></link>
    to know the actual two-phase state.
   </para>
  </refsect1>
@@ -175,12 +175,13 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
          <para>
           See <xref linkend="sql-createsubscription-notes"/> for details of
           how <literal>copy_data = true</literal> can interact with the
-          <literal>origin</literal> parameter.
+          <link linkend="sql-createsubscription-with-origin"><literal>origin</literal></link>
+          parameter.
          </para>
          <para>
-          See the <link linkend="sql-createsubscription-binary"><literal>binary</literal>
-          option</link> of <command>CREATE SUBSCRIPTION</command> for details
-          about copying pre-existing data in binary format.
+          See the <link linkend="sql-createsubscription-with-binary"><literal>binary</literal></link>
+          parameter of <command>CREATE SUBSCRIPTION</command> for details about
+          copying pre-existing data in binary format.
          </para>
         </listitem>
        </varlistentry>
@@ -214,12 +215,13 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
      <para>
       This clause alters parameters originally set by
       <xref linkend="sql-createsubscription"/>.  See there for more
-      information.  The parameters that can be altered
-      are <literal>slot_name</literal>,
-      <literal>synchronous_commit</literal>,
-      <literal>binary</literal>, <literal>streaming</literal>,
-      <literal>disable_on_error</literal>, and
-      <literal>origin</literal>.
+      information.  The parameters that can be altered are
+      <link linkend="sql-createsubscription-with-slot-name"><literal>slot_name</literal></link>,
+      <link linkend="sql-createsubscription-with-synchronous-commit"><literal>synchronous_commit</literal></link>,
+      <link linkend="sql-createsubscription-with-binary"><literal>binary</literal></link>,
+      <link linkend="sql-createsubscription-with-streaming"><literal>streaming</literal></link>,
+      <link linkend="sql-createsubscription-with-disable-on-error"><literal>disable_on_error</literal></link>,
+      and <link linkend="sql-createsubscription-with-origin"><literal>origin</literal></link>.
      </para>
     </listitem>
    </varlistentry>
@@ -233,8 +235,8 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
       resolved.  By using the <command>ALTER SUBSCRIPTION ... SKIP</command> command,
       the logical replication worker skips all data modification changes within
       the transaction.  This option has no effect on the transactions that are
-      already prepared by enabling <literal>two_phase</literal> on
-      subscriber.
+      already prepared by enabling <link linkend="sql-createsubscription-with-two-phase"><literal>two_phase</literal></link>
+      on the subscriber.
       After the logical replication worker successfully skips the transaction or
       finishes a transaction, the LSN (stored in
       <structname>pg_subscription</structname>.<structfield>subskiplsn</structfield>)
diff --git a/doc/src/sgml/ref/create_subscription.sgml b/doc/src/sgml/ref/create_subscription.sgml
index 9d4b9d4e33..a66b8025f3 100644
--- a/doc/src/sgml/ref/create_subscription.sgml
+++ b/doc/src/sgml/ref/create_subscription.sgml
@@ -61,7 +61,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
   <title>Parameters</title>
 
   <variablelist>
-   <varlistentry>
+   <varlistentry id="sql-createsubscription-name">
     <term><replaceable class="parameter">subscription_name</replaceable></term>
     <listitem>
      <para>
@@ -70,7 +70,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
     </listitem>
    </varlistentry>
 
-   <varlistentry>
+   <varlistentry id="sql-createsubscription-connection">
     <term><literal>CONNECTION '<replaceable class="parameter">conninfo</replaceable>'</literal></term>
     <listitem>
      <para>
@@ -81,7 +81,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
     </listitem>
    </varlistentry>
 
-   <varlistentry>
+   <varlistentry id="sql-createsubscription-publication">
     <term><literal>PUBLICATION <replaceable class="parameter">publication_name</replaceable> [, ...]</literal></term>
     <listitem>
      <para>
@@ -90,7 +90,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
     </listitem>
    </varlistentry>
 
-   <varlistentry>
+   <varlistentry id="sql-createsubscription-with">
     <term><literal>WITH ( <replaceable class="parameter">subscription_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] )</literal></term>
     <listitem>
      <para>
@@ -102,7 +102,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
 
       <variablelist>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-connect">
         <term><literal>connect</literal> (<type>boolean</type>)</term>
         <listitem>
          <para>
@@ -129,7 +129,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-create-slot">
         <term><literal>create_slot</literal> (<type>boolean</type>)</term>
         <listitem>
          <para>
@@ -145,7 +145,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-enabled">
         <term><literal>enabled</literal> (<type>boolean</type>)</term>
         <listitem>
          <para>
@@ -156,7 +156,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-slot-name">
         <term><literal>slot_name</literal> (<type>string</type>)</term>
         <listitem>
          <para>
@@ -185,7 +185,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
 
       <variablelist>
 
-       <varlistentry id="sql-createsubscription-binary" xreflabel="binary">
+       <varlistentry id="sql-createsubscription-with-binary">
         <term><literal>binary</literal> (<type>boolean</type>)</term>
         <listitem>
          <para>
@@ -222,7 +222,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-copy-data">
         <term><literal>copy_data</literal> (<type>boolean</type>)</term>
         <listitem>
          <para>
@@ -243,7 +243,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-streaming">
         <term><literal>streaming</literal> (<type>enum</type>)</term>
         <listitem>
          <para>
@@ -271,7 +271,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-synchronous-commit">
         <term><literal>synchronous_commit</literal> (<type>enum</type>)</term>
         <listitem>
          <para>
@@ -303,7 +303,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-two-phase">
         <term><literal>two_phase</literal> (<type>boolean</type>)</term>
         <listitem>
          <para>
@@ -334,7 +334,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-disable-on-error">
         <term><literal>disable_on_error</literal> (<type>boolean</type>)</term>
         <listitem>
          <para>
@@ -346,7 +346,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-origin">
         <term><literal>origin</literal> (<type>string</type>)</term>
         <listitem>
          <para>
diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index d6b1faa804..77299878e0 100644
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -1458,9 +1458,9 @@ CREATE DATABASE foo WITH TEMPLATE template0;
    truncate the target tables before initiating a new full table copy.  If users
    intend to copy initial data during refresh they must create the slot with
    <literal>two_phase = false</literal>.  After the initial sync, the
-   <literal>two_phase</literal> option will be automatically enabled by the
-   subscriber if the subscription had been originally created with
-   <literal>two_phase = true</literal> option.
+   <link linkend="sql-createsubscription-with-two-phase"><literal>two_phase</literal></link>
+   option will be automatically enabled by the subscriber if the subscription
+   had been originally created with <literal>two_phase = true</literal> option.
   </para>
  </refsect1>
 
-- 
2.27.0

From 5059715816bdcd7552c6ba345fab1f2aa93d756b Mon Sep 17 00:00:00 2001
From: Hayato Kuroda <kuroda.hayato@fujitsu.com>
Date: Fri, 24 Mar 2023 11:00:53 +0000
Subject: [PATCH v3 2/2] Add XML ID attributes to create_publication.sgml

This commit adds XML ID attributes to all varlistentries in
create_publication.sgml. Additionally, links are included to refer to publication
options, making documents more readable.
---
 doc/src/sgml/logical-replication.sgml     | 55 ++++++++++++-----------
 doc/src/sgml/ref/alter_publication.sgml   |  6 +--
 doc/src/sgml/ref/create_publication.sgml  | 14 +++---
 doc/src/sgml/ref/create_subscription.sgml | 23 +++++-----
 doc/src/sgml/system-views.sgml            |  6 +--
 5 files changed, 55 insertions(+), 49 deletions(-)

diff --git a/doc/src/sgml/logical-replication.sgml b/doc/src/sgml/logical-replication.sgml
index 4aa643ce94..2e0774f9d0 100644
--- a/doc/src/sgml/logical-replication.sgml
+++ b/doc/src/sgml/logical-replication.sgml
@@ -366,7 +366,7 @@ 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>
@@ -798,11 +798,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>
@@ -826,10 +827,11 @@ 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
-     <xref linkend="logical-replication-snapshot"/>, and see
-     <xref linkend="logical-replication-subscription-examples"/> for examples.
+     <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>
    </warning>
 
@@ -848,7 +850,7 @@ 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:
@@ -860,15 +862,16 @@ 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>
@@ -1133,9 +1136,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>
@@ -1288,7 +1291,8 @@ 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>
@@ -1670,9 +1674,10 @@ 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>
@@ -1716,10 +1721,10 @@ 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><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.
   </para>
 
   <para>
diff --git a/doc/src/sgml/ref/alter_publication.sgml b/doc/src/sgml/ref/alter_publication.sgml
index cd20868bca..a37bb734b7 100644
--- a/doc/src/sgml/ref/alter_publication.sgml
+++ b/doc/src/sgml/ref/alter_publication.sgml
@@ -54,7 +54,7 @@ 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 +79,8 @@ 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
index a2946feaa3..1cea8b4563 100644
--- 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,7 +158,7 @@ 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>
@@ -166,7 +166,7 @@ CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
       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
index a66b8025f3..f4c62c5698 100644
--- a/doc/src/sgml/ref/create_subscription.sgml
+++ b/doc/src/sgml/ref/create_subscription.sgml
@@ -418,17 +418,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
-   <xref linkend="logical-replication-subscription-examples"/> for examples.
+   <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>
 
   <para>
diff --git a/doc/src/sgml/system-views.sgml b/doc/src/sgml/system-views.sgml
index 7c8fc3f654..a6e50dbadb 100644
--- a/doc/src/sgml/system-views.sgml
+++ b/doc/src/sgml/system-views.sgml
@@ -2145,9 +2145,9 @@ 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>
-- 
2.27.0

From 1bc444eab033cfa2d5bd3d8545cbc39326702ccb Mon Sep 17 00:00:00 2001
From: Hayato Kuroda <kuroda.hayato@fujitsu.com>
Date: Wed, 22 Mar 2023 10:14:22 +0000
Subject: [PATCH v4 1/2] Add XML ID attributes to create_subscription.sgml

In commit ecb696, an XML ID attribute was added to only one varlistentry,
creating inconsistency with the commit 78ee60. This commit adds XML ID
attributes to all varlistentries in create_subscription.sgml for consistency.
Additionally, links are added to refer to the subscription options, enhancing
the readability of documents.
---
 doc/src/sgml/config.sgml                  |  4 +--
 doc/src/sgml/logical-replication.sgml     | 35 ++++++++++++-----------
 doc/src/sgml/ref/alter_subscription.sgml  | 34 +++++++++++-----------
 doc/src/sgml/ref/create_subscription.sgml | 30 +++++++++----------
 doc/src/sgml/ref/pg_dump.sgml             |  6 ++--
 5 files changed, 57 insertions(+), 52 deletions(-)

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 71730cc52f..cbcbb10f36 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -11742,8 +11742,8 @@ LOG:  CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1)
         On the publisher side, <varname>logical_replication_mode</varname>
         allows streaming or serializing changes immediately in logical decoding.
         When set to <literal>immediate</literal>, stream each change if the
-        <literal>streaming</literal> option (see optional parameters set by
-        <link linkend="sql-createsubscription"><command>CREATE SUBSCRIPTION</command></link>)
+        <link linkend="sql-createsubscription-with-streaming"><literal>streaming</literal></link>
+        option of <link linkend="sql-createsubscription"><command>CREATE SUBSCRIPTION</command></link>
         is enabled, otherwise, serialize each change.  When set to
         <literal>buffered</literal>, the decoding will stream or serialize
         changes when <varname>logical_decoding_work_mem</varname> is reached.
diff --git a/doc/src/sgml/logical-replication.sgml b/doc/src/sgml/logical-replication.sgml
index 3836d13ad3..1a916d1655 100644
--- a/doc/src/sgml/logical-replication.sgml
+++ b/doc/src/sgml/logical-replication.sgml
@@ -252,8 +252,8 @@
    additional columns not provided by the published table.  Any such columns
    will be filled with the default value as specified in the definition of the
    target table. However, logical replication in binary format is more
-   restrictive. See the <link linkend="sql-createsubscription-binary"><literal>binary</literal>
-   option</link> of <command>CREATE SUBSCRIPTION</command> for details.
+   restrictive. See the <link linkend="sql-createsubscription-with-binary"><literal>binary</literal></link>
+   option of <command>CREATE SUBSCRIPTION</command> for details.
   </para>
 
   <sect2 id="logical-replication-subscription-slot">
@@ -587,7 +587,8 @@ ALTER SUBSCRIPTION
 
    <para>
     Example 2: Where the subscription says <literal>connect = false</literal>,
-    but also specifies the <literal>slot_name</literal>
+    but also specifies the <link linkend="sql-createsubscription-with-slot-name"><literal>slot_name</literal></link>
+    option.
     <itemizedlist>
      <listitem>
       <para>
@@ -704,9 +705,9 @@ ALTER SUBSCRIPTION
     If the row filter evaluates to <literal>false</literal> or <literal>NULL</literal>
     then the row is not replicated. The <literal>WHERE</literal> clause expression
     is evaluated with the same role used for the replication connection (i.e.
-    the role specified in the <literal>CONNECTION</literal> clause of the
-    <xref linkend="sql-createsubscription"/>). Row filters have no effect for
-    <command>TRUNCATE</command> command.
+    the role specified in the <link linkend="sql-createsubscription-connection"><literal>CONNECTION</literal></link>
+    clause of the <xref linkend="sql-createsubscription"/>). Row filters have
+    no effect for <command>TRUNCATE</command> command.
    </para>
 
   </sect2>
@@ -1500,9 +1501,9 @@ CONTEXT:  processing remote data for replication origin "pg_16395" during "INSER
    <function>pg_replication_origin_advance()</function></link> function.
    Before using this function, the subscription needs to be disabled temporarily
    either by <command>ALTER SUBSCRIPTION ... DISABLE</command> or, the
-   subscription can be used with the <literal>disable_on_error</literal> option.
-   Then, you can use <function>pg_replication_origin_advance()</function> function
-   with the <parameter>node_name</parameter> (i.e., <literal>pg_16395</literal>)
+   subscription can be used with the <link linkend="sql-createsubscription-with-disable-on-error"><literal>disable_on_error</literal></link>
+   option. Then, you can use <function>pg_replication_origin_advance()</function>
+   function with the <parameter>node_name</parameter> (i.e., <literal>pg_16395</literal>)
    and the next LSN of the finish LSN (i.e., 0/14C0379).  The current position of
    origins can be seen in the <link linkend="view-pg-replication-origin-status">
    <structname>pg_replication_origin_status</structname></link> system view.
@@ -1512,11 +1513,12 @@ CONTEXT:  processing remote data for replication origin "pg_16395" during "INSER
   </para>
 
   <para>
-   When the streaming mode is <literal>parallel</literal>, the finish LSN of
-   failed transactions may not be logged. In that case, it may be necessary to
-   change the streaming mode to <literal>on</literal> or <literal>off</literal> and
-   cause the same conflicts again so the finish LSN of the failed transaction will
-   be written to the server log. For the usage of finish LSN, please refer to <link
+   When the <link linkend="sql-createsubscription-with-streaming"><literal>streaming</literal></link>
+   mode is <literal>parallel</literal>, the finish LSN of failed transactions
+   may not be logged. In that case, it may be necessary to change the streaming
+   mode to <literal>on</literal> or <literal>off</literal> and cause the same
+   conflicts again so the finish LSN of the failed transaction will be written
+   to the server log. For the usage of finish LSN, please refer to <link
    linkend="sql-altersubscription"><command>ALTER SUBSCRIPTION ...
    SKIP</command></link>.
   </para>
@@ -1701,8 +1703,9 @@ CONTEXT:  processing remote data for replication origin "pg_16395" during "INSER
    subscription.  A disabled subscription or a crashed subscription will have
    zero rows in this view.  If the initial data synchronization of any
    table is in progress, there will be additional workers for the tables
-   being synchronized. Moreover, if the streaming transaction is applied in
-   parallel, there may be additional parallel apply workers.
+   being synchronized. Moreover, if the <link linkend="sql-createsubscription-with-streaming"><literal>streaming</literal></link>
+   transaction is applied in parallel, there may be additional parallel apply
+   workers.
   </para>
  </sect1>
 
diff --git a/doc/src/sgml/ref/alter_subscription.sgml b/doc/src/sgml/ref/alter_subscription.sgml
index e92346edef..b7e6d2e83a 100644
--- a/doc/src/sgml/ref/alter_subscription.sgml
+++ b/doc/src/sgml/ref/alter_subscription.sgml
@@ -71,10 +71,10 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
    executed inside a transaction block.
 
    These commands also cannot be executed when the subscription has
-   <literal>two_phase</literal> commit enabled,
-   unless <literal>copy_data</literal> is <literal>false</literal>.
-   See column <structfield>subtwophasestate</structfield> of
-   <link linkend="catalog-pg-subscription"><structname>pg_subscription</structname></link>
+   <link linkend="sql-createsubscription-with-two-phase"><literal>two_phase</literal></link>
+   commit enabled, unless <link linkend="sql-createsubscription-with-copy-data"><literal>copy_data</literal></link>
+   is <literal>false</literal>. See column <structfield>subtwophasestate</structfield>
+   of <link linkend="catalog-pg-subscription"><structname>pg_subscription</structname></link>
    to know the actual two-phase state.
   </para>
  </refsect1>
@@ -175,12 +175,13 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
          <para>
           See <xref linkend="sql-createsubscription-notes"/> for details of
           how <literal>copy_data = true</literal> can interact with the
-          <literal>origin</literal> parameter.
+          <link linkend="sql-createsubscription-with-origin"><literal>origin</literal></link>
+          parameter.
          </para>
          <para>
-          See the <link linkend="sql-createsubscription-binary"><literal>binary</literal>
-          option</link> of <command>CREATE SUBSCRIPTION</command> for details
-          about copying pre-existing data in binary format.
+          See the <link linkend="sql-createsubscription-with-binary"><literal>binary</literal></link>
+          parameter of <command>CREATE SUBSCRIPTION</command> for details about
+          copying pre-existing data in binary format.
          </para>
         </listitem>
        </varlistentry>
@@ -214,12 +215,13 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
      <para>
       This clause alters parameters originally set by
       <xref linkend="sql-createsubscription"/>.  See there for more
-      information.  The parameters that can be altered
-      are <literal>slot_name</literal>,
-      <literal>synchronous_commit</literal>,
-      <literal>binary</literal>, <literal>streaming</literal>,
-      <literal>disable_on_error</literal>, and
-      <literal>origin</literal>.
+      information.  The parameters that can be altered are
+      <link linkend="sql-createsubscription-with-slot-name"><literal>slot_name</literal></link>,
+      <link linkend="sql-createsubscription-with-synchronous-commit"><literal>synchronous_commit</literal></link>,
+      <link linkend="sql-createsubscription-with-binary"><literal>binary</literal></link>,
+      <link linkend="sql-createsubscription-with-streaming"><literal>streaming</literal></link>,
+      <link linkend="sql-createsubscription-with-disable-on-error"><literal>disable_on_error</literal></link>,
+      and <link linkend="sql-createsubscription-with-origin"><literal>origin</literal></link>.
      </para>
     </listitem>
    </varlistentry>
@@ -233,8 +235,8 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
       resolved.  By using the <command>ALTER SUBSCRIPTION ... SKIP</command> command,
       the logical replication worker skips all data modification changes within
       the transaction.  This option has no effect on the transactions that are
-      already prepared by enabling <literal>two_phase</literal> on
-      subscriber.
+      already prepared by enabling <link linkend="sql-createsubscription-with-two-phase"><literal>two_phase</literal></link>
+      on the subscriber.
       After the logical replication worker successfully skips the transaction or
       finishes a transaction, the LSN (stored in
       <structname>pg_subscription</structname>.<structfield>subskiplsn</structfield>)
diff --git a/doc/src/sgml/ref/create_subscription.sgml b/doc/src/sgml/ref/create_subscription.sgml
index 9d4b9d4e33..a66b8025f3 100644
--- a/doc/src/sgml/ref/create_subscription.sgml
+++ b/doc/src/sgml/ref/create_subscription.sgml
@@ -61,7 +61,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
   <title>Parameters</title>
 
   <variablelist>
-   <varlistentry>
+   <varlistentry id="sql-createsubscription-name">
     <term><replaceable class="parameter">subscription_name</replaceable></term>
     <listitem>
      <para>
@@ -70,7 +70,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
     </listitem>
    </varlistentry>
 
-   <varlistentry>
+   <varlistentry id="sql-createsubscription-connection">
     <term><literal>CONNECTION '<replaceable class="parameter">conninfo</replaceable>'</literal></term>
     <listitem>
      <para>
@@ -81,7 +81,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
     </listitem>
    </varlistentry>
 
-   <varlistentry>
+   <varlistentry id="sql-createsubscription-publication">
     <term><literal>PUBLICATION <replaceable class="parameter">publication_name</replaceable> [, ...]</literal></term>
     <listitem>
      <para>
@@ -90,7 +90,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
     </listitem>
    </varlistentry>
 
-   <varlistentry>
+   <varlistentry id="sql-createsubscription-with">
     <term><literal>WITH ( <replaceable class="parameter">subscription_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] )</literal></term>
     <listitem>
      <para>
@@ -102,7 +102,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
 
       <variablelist>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-connect">
         <term><literal>connect</literal> (<type>boolean</type>)</term>
         <listitem>
          <para>
@@ -129,7 +129,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-create-slot">
         <term><literal>create_slot</literal> (<type>boolean</type>)</term>
         <listitem>
          <para>
@@ -145,7 +145,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-enabled">
         <term><literal>enabled</literal> (<type>boolean</type>)</term>
         <listitem>
          <para>
@@ -156,7 +156,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-slot-name">
         <term><literal>slot_name</literal> (<type>string</type>)</term>
         <listitem>
          <para>
@@ -185,7 +185,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
 
       <variablelist>
 
-       <varlistentry id="sql-createsubscription-binary" xreflabel="binary">
+       <varlistentry id="sql-createsubscription-with-binary">
         <term><literal>binary</literal> (<type>boolean</type>)</term>
         <listitem>
          <para>
@@ -222,7 +222,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-copy-data">
         <term><literal>copy_data</literal> (<type>boolean</type>)</term>
         <listitem>
          <para>
@@ -243,7 +243,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-streaming">
         <term><literal>streaming</literal> (<type>enum</type>)</term>
         <listitem>
          <para>
@@ -271,7 +271,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-synchronous-commit">
         <term><literal>synchronous_commit</literal> (<type>enum</type>)</term>
         <listitem>
          <para>
@@ -303,7 +303,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-two-phase">
         <term><literal>two_phase</literal> (<type>boolean</type>)</term>
         <listitem>
          <para>
@@ -334,7 +334,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-disable-on-error">
         <term><literal>disable_on_error</literal> (<type>boolean</type>)</term>
         <listitem>
          <para>
@@ -346,7 +346,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-origin">
         <term><literal>origin</literal> (<type>string</type>)</term>
         <listitem>
          <para>
diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index d6b1faa804..77299878e0 100644
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -1458,9 +1458,9 @@ CREATE DATABASE foo WITH TEMPLATE template0;
    truncate the target tables before initiating a new full table copy.  If users
    intend to copy initial data during refresh they must create the slot with
    <literal>two_phase = false</literal>.  After the initial sync, the
-   <literal>two_phase</literal> option will be automatically enabled by the
-   subscriber if the subscription had been originally created with
-   <literal>two_phase = true</literal> option.
+   <link linkend="sql-createsubscription-with-two-phase"><literal>two_phase</literal></link>
+   option will be automatically enabled by the subscriber if the subscription
+   had been originally created with <literal>two_phase = true</literal> option.
   </para>
  </refsect1>
 
-- 
2.27.0

From cde515ab5f28222b939ccda31cb32e8422c9eccb Mon Sep 17 00:00:00 2001
From: Hayato Kuroda <kuroda.hayato@fujitsu.com>
Date: Fri, 24 Mar 2023 11:00:53 +0000
Subject: [PATCH v4 2/2] Add XML ID attributes to create_publication.sgml

This commit adds XML ID attributes to all varlistentries in
create_publication.sgml. Additionally, links are included to refer to publication
options, making documents more readable.
---
 doc/src/sgml/logical-replication.sgml     | 66 ++++++++++++-----------
 doc/src/sgml/ref/alter_publication.sgml   |  6 +--
 doc/src/sgml/ref/create_publication.sgml  | 14 ++---
 doc/src/sgml/ref/create_subscription.sgml | 23 ++++----
 doc/src/sgml/system-views.sgml            |  6 +--
 5 files changed, 61 insertions(+), 54 deletions(-)

diff --git a/doc/src/sgml/logical-replication.sgml b/doc/src/sgml/logical-replication.sgml
index 1a916d1655..2cf6218352 100644
--- a/doc/src/sgml/logical-replication.sgml
+++ b/doc/src/sgml/logical-replication.sgml
@@ -366,7 +366,7 @@ 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>
@@ -798,11 +798,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>
@@ -826,10 +827,11 @@ 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
-     <xref linkend="logical-replication-snapshot"/>, and see
-     <xref linkend="logical-replication-subscription-examples"/> for examples.
+     <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>
    </warning>
 
@@ -848,7 +850,7 @@ 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:
@@ -860,15 +862,16 @@ 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>
@@ -1133,9 +1136,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>
@@ -1288,15 +1291,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>
 
@@ -1605,7 +1609,8 @@ 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>
+     of <command>CREATE PUBLICATION</command>).
     </para>
    </listitem>
   </itemizedlist>
@@ -1671,9 +1676,10 @@ 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>
@@ -1718,10 +1724,10 @@ 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
index cd20868bca..a37bb734b7 100644
--- a/doc/src/sgml/ref/alter_publication.sgml
+++ b/doc/src/sgml/ref/alter_publication.sgml
@@ -54,7 +54,7 @@ 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 +79,8 @@ 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
index a2946feaa3..1cea8b4563 100644
--- 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,7 +158,7 @@ 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>
@@ -166,7 +166,7 @@ CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
       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
index a66b8025f3..f4c62c5698 100644
--- a/doc/src/sgml/ref/create_subscription.sgml
+++ b/doc/src/sgml/ref/create_subscription.sgml
@@ -418,17 +418,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
-   <xref linkend="logical-replication-subscription-examples"/> for examples.
+   <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>
 
   <para>
diff --git a/doc/src/sgml/system-views.sgml b/doc/src/sgml/system-views.sgml
index 7c8fc3f654..a6e50dbadb 100644
--- a/doc/src/sgml/system-views.sgml
+++ b/doc/src/sgml/system-views.sgml
@@ -2145,9 +2145,9 @@ 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>
-- 
2.27.0

From 1bc444eab033cfa2d5bd3d8545cbc39326702ccb Mon Sep 17 00:00:00 2001
From: Hayato Kuroda <kuroda.hayato@fujitsu.com>
Date: Wed, 22 Mar 2023 10:14:22 +0000
Subject: [PATCH v5 1/2] Add XML ID attributes to create_subscription.sgml

In commit ecb696, an XML ID attribute was added to only one varlistentry,
creating inconsistency with the commit 78ee60. This commit adds XML ID
attributes to all varlistentries in create_subscription.sgml for consistency.
Additionally, links are added to refer to the subscription options, enhancing
the readability of documents.
---
 doc/src/sgml/config.sgml                  |  4 +--
 doc/src/sgml/logical-replication.sgml     | 35 ++++++++++++-----------
 doc/src/sgml/ref/alter_subscription.sgml  | 34 +++++++++++-----------
 doc/src/sgml/ref/create_subscription.sgml | 30 +++++++++----------
 doc/src/sgml/ref/pg_dump.sgml             |  6 ++--
 5 files changed, 57 insertions(+), 52 deletions(-)

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 71730cc52f..cbcbb10f36 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -11742,8 +11742,8 @@ LOG:  CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1)
         On the publisher side, <varname>logical_replication_mode</varname>
         allows streaming or serializing changes immediately in logical decoding.
         When set to <literal>immediate</literal>, stream each change if the
-        <literal>streaming</literal> option (see optional parameters set by
-        <link linkend="sql-createsubscription"><command>CREATE SUBSCRIPTION</command></link>)
+        <link linkend="sql-createsubscription-with-streaming"><literal>streaming</literal></link>
+        option of <link linkend="sql-createsubscription"><command>CREATE SUBSCRIPTION</command></link>
         is enabled, otherwise, serialize each change.  When set to
         <literal>buffered</literal>, the decoding will stream or serialize
         changes when <varname>logical_decoding_work_mem</varname> is reached.
diff --git a/doc/src/sgml/logical-replication.sgml b/doc/src/sgml/logical-replication.sgml
index 3836d13ad3..1a916d1655 100644
--- a/doc/src/sgml/logical-replication.sgml
+++ b/doc/src/sgml/logical-replication.sgml
@@ -252,8 +252,8 @@
    additional columns not provided by the published table.  Any such columns
    will be filled with the default value as specified in the definition of the
    target table. However, logical replication in binary format is more
-   restrictive. See the <link linkend="sql-createsubscription-binary"><literal>binary</literal>
-   option</link> of <command>CREATE SUBSCRIPTION</command> for details.
+   restrictive. See the <link linkend="sql-createsubscription-with-binary"><literal>binary</literal></link>
+   option of <command>CREATE SUBSCRIPTION</command> for details.
   </para>
 
   <sect2 id="logical-replication-subscription-slot">
@@ -587,7 +587,8 @@ ALTER SUBSCRIPTION
 
    <para>
     Example 2: Where the subscription says <literal>connect = false</literal>,
-    but also specifies the <literal>slot_name</literal>
+    but also specifies the <link linkend="sql-createsubscription-with-slot-name"><literal>slot_name</literal></link>
+    option.
     <itemizedlist>
      <listitem>
       <para>
@@ -704,9 +705,9 @@ ALTER SUBSCRIPTION
     If the row filter evaluates to <literal>false</literal> or <literal>NULL</literal>
     then the row is not replicated. The <literal>WHERE</literal> clause expression
     is evaluated with the same role used for the replication connection (i.e.
-    the role specified in the <literal>CONNECTION</literal> clause of the
-    <xref linkend="sql-createsubscription"/>). Row filters have no effect for
-    <command>TRUNCATE</command> command.
+    the role specified in the <link linkend="sql-createsubscription-connection"><literal>CONNECTION</literal></link>
+    clause of the <xref linkend="sql-createsubscription"/>). Row filters have
+    no effect for <command>TRUNCATE</command> command.
    </para>
 
   </sect2>
@@ -1500,9 +1501,9 @@ CONTEXT:  processing remote data for replication origin "pg_16395" during "INSER
    <function>pg_replication_origin_advance()</function></link> function.
    Before using this function, the subscription needs to be disabled temporarily
    either by <command>ALTER SUBSCRIPTION ... DISABLE</command> or, the
-   subscription can be used with the <literal>disable_on_error</literal> option.
-   Then, you can use <function>pg_replication_origin_advance()</function> function
-   with the <parameter>node_name</parameter> (i.e., <literal>pg_16395</literal>)
+   subscription can be used with the <link linkend="sql-createsubscription-with-disable-on-error"><literal>disable_on_error</literal></link>
+   option. Then, you can use <function>pg_replication_origin_advance()</function>
+   function with the <parameter>node_name</parameter> (i.e., <literal>pg_16395</literal>)
    and the next LSN of the finish LSN (i.e., 0/14C0379).  The current position of
    origins can be seen in the <link linkend="view-pg-replication-origin-status">
    <structname>pg_replication_origin_status</structname></link> system view.
@@ -1512,11 +1513,12 @@ CONTEXT:  processing remote data for replication origin "pg_16395" during "INSER
   </para>
 
   <para>
-   When the streaming mode is <literal>parallel</literal>, the finish LSN of
-   failed transactions may not be logged. In that case, it may be necessary to
-   change the streaming mode to <literal>on</literal> or <literal>off</literal> and
-   cause the same conflicts again so the finish LSN of the failed transaction will
-   be written to the server log. For the usage of finish LSN, please refer to <link
+   When the <link linkend="sql-createsubscription-with-streaming"><literal>streaming</literal></link>
+   mode is <literal>parallel</literal>, the finish LSN of failed transactions
+   may not be logged. In that case, it may be necessary to change the streaming
+   mode to <literal>on</literal> or <literal>off</literal> and cause the same
+   conflicts again so the finish LSN of the failed transaction will be written
+   to the server log. For the usage of finish LSN, please refer to <link
    linkend="sql-altersubscription"><command>ALTER SUBSCRIPTION ...
    SKIP</command></link>.
   </para>
@@ -1701,8 +1703,9 @@ CONTEXT:  processing remote data for replication origin "pg_16395" during "INSER
    subscription.  A disabled subscription or a crashed subscription will have
    zero rows in this view.  If the initial data synchronization of any
    table is in progress, there will be additional workers for the tables
-   being synchronized. Moreover, if the streaming transaction is applied in
-   parallel, there may be additional parallel apply workers.
+   being synchronized. Moreover, if the <link linkend="sql-createsubscription-with-streaming"><literal>streaming</literal></link>
+   transaction is applied in parallel, there may be additional parallel apply
+   workers.
   </para>
  </sect1>
 
diff --git a/doc/src/sgml/ref/alter_subscription.sgml b/doc/src/sgml/ref/alter_subscription.sgml
index e92346edef..b7e6d2e83a 100644
--- a/doc/src/sgml/ref/alter_subscription.sgml
+++ b/doc/src/sgml/ref/alter_subscription.sgml
@@ -71,10 +71,10 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
    executed inside a transaction block.
 
    These commands also cannot be executed when the subscription has
-   <literal>two_phase</literal> commit enabled,
-   unless <literal>copy_data</literal> is <literal>false</literal>.
-   See column <structfield>subtwophasestate</structfield> of
-   <link linkend="catalog-pg-subscription"><structname>pg_subscription</structname></link>
+   <link linkend="sql-createsubscription-with-two-phase"><literal>two_phase</literal></link>
+   commit enabled, unless <link linkend="sql-createsubscription-with-copy-data"><literal>copy_data</literal></link>
+   is <literal>false</literal>. See column <structfield>subtwophasestate</structfield>
+   of <link linkend="catalog-pg-subscription"><structname>pg_subscription</structname></link>
    to know the actual two-phase state.
   </para>
  </refsect1>
@@ -175,12 +175,13 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
          <para>
           See <xref linkend="sql-createsubscription-notes"/> for details of
           how <literal>copy_data = true</literal> can interact with the
-          <literal>origin</literal> parameter.
+          <link linkend="sql-createsubscription-with-origin"><literal>origin</literal></link>
+          parameter.
          </para>
          <para>
-          See the <link linkend="sql-createsubscription-binary"><literal>binary</literal>
-          option</link> of <command>CREATE SUBSCRIPTION</command> for details
-          about copying pre-existing data in binary format.
+          See the <link linkend="sql-createsubscription-with-binary"><literal>binary</literal></link>
+          parameter of <command>CREATE SUBSCRIPTION</command> for details about
+          copying pre-existing data in binary format.
          </para>
         </listitem>
        </varlistentry>
@@ -214,12 +215,13 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
      <para>
       This clause alters parameters originally set by
       <xref linkend="sql-createsubscription"/>.  See there for more
-      information.  The parameters that can be altered
-      are <literal>slot_name</literal>,
-      <literal>synchronous_commit</literal>,
-      <literal>binary</literal>, <literal>streaming</literal>,
-      <literal>disable_on_error</literal>, and
-      <literal>origin</literal>.
+      information.  The parameters that can be altered are
+      <link linkend="sql-createsubscription-with-slot-name"><literal>slot_name</literal></link>,
+      <link linkend="sql-createsubscription-with-synchronous-commit"><literal>synchronous_commit</literal></link>,
+      <link linkend="sql-createsubscription-with-binary"><literal>binary</literal></link>,
+      <link linkend="sql-createsubscription-with-streaming"><literal>streaming</literal></link>,
+      <link linkend="sql-createsubscription-with-disable-on-error"><literal>disable_on_error</literal></link>,
+      and <link linkend="sql-createsubscription-with-origin"><literal>origin</literal></link>.
      </para>
     </listitem>
    </varlistentry>
@@ -233,8 +235,8 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
       resolved.  By using the <command>ALTER SUBSCRIPTION ... SKIP</command> command,
       the logical replication worker skips all data modification changes within
       the transaction.  This option has no effect on the transactions that are
-      already prepared by enabling <literal>two_phase</literal> on
-      subscriber.
+      already prepared by enabling <link linkend="sql-createsubscription-with-two-phase"><literal>two_phase</literal></link>
+      on the subscriber.
       After the logical replication worker successfully skips the transaction or
       finishes a transaction, the LSN (stored in
       <structname>pg_subscription</structname>.<structfield>subskiplsn</structfield>)
diff --git a/doc/src/sgml/ref/create_subscription.sgml b/doc/src/sgml/ref/create_subscription.sgml
index 9d4b9d4e33..a66b8025f3 100644
--- a/doc/src/sgml/ref/create_subscription.sgml
+++ b/doc/src/sgml/ref/create_subscription.sgml
@@ -61,7 +61,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
   <title>Parameters</title>
 
   <variablelist>
-   <varlistentry>
+   <varlistentry id="sql-createsubscription-name">
     <term><replaceable class="parameter">subscription_name</replaceable></term>
     <listitem>
      <para>
@@ -70,7 +70,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
     </listitem>
    </varlistentry>
 
-   <varlistentry>
+   <varlistentry id="sql-createsubscription-connection">
     <term><literal>CONNECTION '<replaceable class="parameter">conninfo</replaceable>'</literal></term>
     <listitem>
      <para>
@@ -81,7 +81,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
     </listitem>
    </varlistentry>
 
-   <varlistentry>
+   <varlistentry id="sql-createsubscription-publication">
     <term><literal>PUBLICATION <replaceable class="parameter">publication_name</replaceable> [, ...]</literal></term>
     <listitem>
      <para>
@@ -90,7 +90,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
     </listitem>
    </varlistentry>
 
-   <varlistentry>
+   <varlistentry id="sql-createsubscription-with">
     <term><literal>WITH ( <replaceable class="parameter">subscription_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] )</literal></term>
     <listitem>
      <para>
@@ -102,7 +102,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
 
       <variablelist>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-connect">
         <term><literal>connect</literal> (<type>boolean</type>)</term>
         <listitem>
          <para>
@@ -129,7 +129,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-create-slot">
         <term><literal>create_slot</literal> (<type>boolean</type>)</term>
         <listitem>
          <para>
@@ -145,7 +145,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-enabled">
         <term><literal>enabled</literal> (<type>boolean</type>)</term>
         <listitem>
          <para>
@@ -156,7 +156,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-slot-name">
         <term><literal>slot_name</literal> (<type>string</type>)</term>
         <listitem>
          <para>
@@ -185,7 +185,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
 
       <variablelist>
 
-       <varlistentry id="sql-createsubscription-binary" xreflabel="binary">
+       <varlistentry id="sql-createsubscription-with-binary">
         <term><literal>binary</literal> (<type>boolean</type>)</term>
         <listitem>
          <para>
@@ -222,7 +222,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-copy-data">
         <term><literal>copy_data</literal> (<type>boolean</type>)</term>
         <listitem>
          <para>
@@ -243,7 +243,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-streaming">
         <term><literal>streaming</literal> (<type>enum</type>)</term>
         <listitem>
          <para>
@@ -271,7 +271,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-synchronous-commit">
         <term><literal>synchronous_commit</literal> (<type>enum</type>)</term>
         <listitem>
          <para>
@@ -303,7 +303,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-two-phase">
         <term><literal>two_phase</literal> (<type>boolean</type>)</term>
         <listitem>
          <para>
@@ -334,7 +334,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-disable-on-error">
         <term><literal>disable_on_error</literal> (<type>boolean</type>)</term>
         <listitem>
          <para>
@@ -346,7 +346,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-origin">
         <term><literal>origin</literal> (<type>string</type>)</term>
         <listitem>
          <para>
diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index d6b1faa804..77299878e0 100644
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -1458,9 +1458,9 @@ CREATE DATABASE foo WITH TEMPLATE template0;
    truncate the target tables before initiating a new full table copy.  If users
    intend to copy initial data during refresh they must create the slot with
    <literal>two_phase = false</literal>.  After the initial sync, the
-   <literal>two_phase</literal> option will be automatically enabled by the
-   subscriber if the subscription had been originally created with
-   <literal>two_phase = true</literal> option.
+   <link linkend="sql-createsubscription-with-two-phase"><literal>two_phase</literal></link>
+   option will be automatically enabled by the subscriber if the subscription
+   had been originally created with <literal>two_phase = true</literal> option.
   </para>
  </refsect1>
 
-- 
2.27.0

From 83f512bdfcc34ca6c5463b8217e2000c4285b08d Mon Sep 17 00:00:00 2001
From: Hayato Kuroda <kuroda.hayato@fujitsu.com>
Date: Fri, 24 Mar 2023 11:00:53 +0000
Subject: [PATCH v5 2/2] Add XML ID attributes to create_publication.sgml

This commit adds XML ID attributes to all varlistentries in
create_publication.sgml. Additionally, links are included to refer to publication
options, making documents more readable.
---
 doc/src/sgml/logical-replication.sgml     | 66 ++++++++++++-----------
 doc/src/sgml/ref/alter_publication.sgml   |  6 +--
 doc/src/sgml/ref/create_publication.sgml  | 14 ++---
 doc/src/sgml/ref/create_subscription.sgml | 23 ++++----
 doc/src/sgml/system-views.sgml            |  6 +--
 5 files changed, 61 insertions(+), 54 deletions(-)

diff --git a/doc/src/sgml/logical-replication.sgml b/doc/src/sgml/logical-replication.sgml
index 1a916d1655..e4d2560711 100644
--- a/doc/src/sgml/logical-replication.sgml
+++ b/doc/src/sgml/logical-replication.sgml
@@ -366,7 +366,7 @@ 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>
@@ -798,11 +798,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>
@@ -826,10 +827,11 @@ 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
-     <xref linkend="logical-replication-snapshot"/>, and see
-     <xref linkend="logical-replication-subscription-examples"/> for examples.
+     <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>
    </warning>
 
@@ -848,7 +850,7 @@ 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:
@@ -860,15 +862,16 @@ 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>
@@ -1133,9 +1136,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>
@@ -1288,15 +1291,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>
 
@@ -1605,7 +1609,8 @@ 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>
@@ -1671,9 +1676,10 @@ 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>
@@ -1718,10 +1724,10 @@ 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
index cd20868bca..a37bb734b7 100644
--- a/doc/src/sgml/ref/alter_publication.sgml
+++ b/doc/src/sgml/ref/alter_publication.sgml
@@ -54,7 +54,7 @@ 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 +79,8 @@ 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
index a2946feaa3..1cea8b4563 100644
--- 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,7 +158,7 @@ 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>
@@ -166,7 +166,7 @@ CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
       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
index a66b8025f3..f4c62c5698 100644
--- a/doc/src/sgml/ref/create_subscription.sgml
+++ b/doc/src/sgml/ref/create_subscription.sgml
@@ -418,17 +418,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
-   <xref linkend="logical-replication-subscription-examples"/> for examples.
+   <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>
 
   <para>
diff --git a/doc/src/sgml/system-views.sgml b/doc/src/sgml/system-views.sgml
index 7c8fc3f654..a6e50dbadb 100644
--- a/doc/src/sgml/system-views.sgml
+++ b/doc/src/sgml/system-views.sgml
@@ -2145,9 +2145,9 @@ 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>
-- 
2.27.0

From 6028ae381ad391651aa3eedf8d9e608981a715c0 Mon Sep 17 00:00:00 2001
From: Hayato Kuroda <kuroda.hayato@fujitsu.com>
Date: Wed, 22 Mar 2023 10:14:22 +0000
Subject: [PATCH v6] Add XML ID attributes to create_subscription.sgml

In commit ecb696, an XML ID attribute was added to only one varlistentry,
creating inconsistency with the commit 78ee60. This commit adds XML ID
attributes to all varlistentries in create_subscription.sgml for consistency.
Additionally, links are added to refer to the subscription options, enhancing
the readability of documents.
---
 doc/src/sgml/config.sgml                  |  7 ++--
 doc/src/sgml/logical-replication.sgml     | 44 +++++++++++---------
 doc/src/sgml/ref/alter_subscription.sgml  | 49 ++++++++++++-----------
 doc/src/sgml/ref/create_subscription.sgml | 30 +++++++-------
 doc/src/sgml/ref/pg_dump.sgml             |  7 ++--
 5 files changed, 75 insertions(+), 62 deletions(-)

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 71730cc52f..a1c36b4353 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -11742,9 +11742,10 @@ LOG:  CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1)
         On the publisher side, <varname>logical_replication_mode</varname>
         allows streaming or serializing changes immediately in logical decoding.
         When set to <literal>immediate</literal>, stream each change if the
-        <literal>streaming</literal> option (see optional parameters set by
-        <link linkend="sql-createsubscription"><command>CREATE SUBSCRIPTION</command></link>)
-        is enabled, otherwise, serialize each change.  When set to
+        <link linkend="sql-createsubscription-with-streaming">
+        <literal>streaming</literal></link> option of <link
+        linkend="sql-createsubscription"><command>CREATE SUBSCRIPTION</command>
+        </link> is enabled, otherwise, serialize each change. When set to
         <literal>buffered</literal>, the decoding will stream or serialize
         changes when <varname>logical_decoding_work_mem</varname> is reached.
        </para>
diff --git a/doc/src/sgml/logical-replication.sgml b/doc/src/sgml/logical-replication.sgml
index 3836d13ad3..3540be08e7 100644
--- a/doc/src/sgml/logical-replication.sgml
+++ b/doc/src/sgml/logical-replication.sgml
@@ -252,8 +252,9 @@
    additional columns not provided by the published table.  Any such columns
    will be filled with the default value as specified in the definition of the
    target table. However, logical replication in binary format is more
-   restrictive. See the <link linkend="sql-createsubscription-binary"><literal>binary</literal>
-   option</link> of <command>CREATE SUBSCRIPTION</command> for details.
+   restrictive. See the <link linkend="sql-createsubscription-with-binary">
+   <literal>binary</literal></link> option of <command>CREATE SUBSCRIPTION</command>
+   for details.
   </para>
 
   <sect2 id="logical-replication-subscription-slot">
@@ -587,7 +588,8 @@ ALTER SUBSCRIPTION
 
    <para>
     Example 2: Where the subscription says <literal>connect = false</literal>,
-    but also specifies the <literal>slot_name</literal>
+    but also specifies the <link linkend="sql-createsubscription-with-slot-name">
+    <literal>slot_name</literal></link> option.
     <itemizedlist>
      <listitem>
       <para>
@@ -704,8 +706,9 @@ ALTER SUBSCRIPTION
     If the row filter evaluates to <literal>false</literal> or <literal>NULL</literal>
     then the row is not replicated. The <literal>WHERE</literal> clause expression
     is evaluated with the same role used for the replication connection (i.e.
-    the role specified in the <literal>CONNECTION</literal> clause of the
-    <xref linkend="sql-createsubscription"/>). Row filters have no effect for
+    the role specified in the <link linkend="sql-createsubscription-connection">
+    <literal>CONNECTION</literal></link> clause of the <xref
+    linkend="sql-createsubscription"/>). Row filters have no effect for
     <command>TRUNCATE</command> command.
    </para>
 
@@ -1500,10 +1503,12 @@ CONTEXT:  processing remote data for replication origin "pg_16395" during "INSER
    <function>pg_replication_origin_advance()</function></link> function.
    Before using this function, the subscription needs to be disabled temporarily
    either by <command>ALTER SUBSCRIPTION ... DISABLE</command> or, the
-   subscription can be used with the <literal>disable_on_error</literal> option.
-   Then, you can use <function>pg_replication_origin_advance()</function> function
-   with the <parameter>node_name</parameter> (i.e., <literal>pg_16395</literal>)
-   and the next LSN of the finish LSN (i.e., 0/14C0379).  The current position of
+   subscription can be used with the <link
+   linkend="sql-createsubscription-with-disable-on-error">
+   <literal>disable_on_error</literal></link> option. Then, you can use
+   <function>pg_replication_origin_advance()</function> function with the
+   <parameter>node_name</parameter> (i.e., <literal>pg_16395</literal>) and the
+   next LSN of the finish LSN (i.e., 0/14C0379).  The current position of
    origins can be seen in the <link linkend="view-pg-replication-origin-status">
    <structname>pg_replication_origin_status</structname></link> system view.
    Please note that skipping the whole transaction includes skipping changes that
@@ -1512,13 +1517,14 @@ CONTEXT:  processing remote data for replication origin "pg_16395" during "INSER
   </para>
 
   <para>
-   When the streaming mode is <literal>parallel</literal>, the finish LSN of
-   failed transactions may not be logged. In that case, it may be necessary to
-   change the streaming mode to <literal>on</literal> or <literal>off</literal> and
-   cause the same conflicts again so the finish LSN of the failed transaction will
-   be written to the server log. For the usage of finish LSN, please refer to <link
-   linkend="sql-altersubscription"><command>ALTER SUBSCRIPTION ...
-   SKIP</command></link>.
+   When the <link linkend="sql-createsubscription-with-streaming">
+   <literal>streaming</literal></link> mode is <literal>parallel</literal>, the
+   finish LSN of failed transactions may not be logged. In that case, it may be
+   necessary to change the streaming mode to <literal>on</literal> or
+   <literal>off</literal> and cause the same conflicts again so the finish LSN
+   of the failed transaction will be written to the server log. For the usage
+   of finish LSN, please refer to <link linkend="sql-altersubscription">
+   <command>ALTER SUBSCRIPTION ... SKIP</command></link>.
   </para>
  </sect1>
 
@@ -1701,8 +1707,10 @@ CONTEXT:  processing remote data for replication origin "pg_16395" during "INSER
    subscription.  A disabled subscription or a crashed subscription will have
    zero rows in this view.  If the initial data synchronization of any
    table is in progress, there will be additional workers for the tables
-   being synchronized. Moreover, if the streaming transaction is applied in
-   parallel, there may be additional parallel apply workers.
+   being synchronized. Moreover, if the <link
+   linkend="sql-createsubscription-with-streaming"><literal>streaming</literal>
+   </link> transaction is applied in parallel, there may be additional parallel
+   apply workers.
   </para>
  </sect1>
 
diff --git a/doc/src/sgml/ref/alter_subscription.sgml b/doc/src/sgml/ref/alter_subscription.sgml
index e92346edef..a7e1e6bb41 100644
--- a/doc/src/sgml/ref/alter_subscription.sgml
+++ b/doc/src/sgml/ref/alter_subscription.sgml
@@ -71,11 +71,12 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
    executed inside a transaction block.
 
    These commands also cannot be executed when the subscription has
-   <literal>two_phase</literal> commit enabled,
-   unless <literal>copy_data</literal> is <literal>false</literal>.
-   See column <structfield>subtwophasestate</structfield> of
-   <link linkend="catalog-pg-subscription"><structname>pg_subscription</structname></link>
-   to know the actual two-phase state.
+   <link linkend="sql-createsubscription-with-two-phase"><literal>two_phase</literal>
+   </link> commit enabled, unless <link linkend="sql-createsubscription-with-copy-data">
+   <literal>copy_data</literal></link> is <literal>false</literal>. See column
+   <structfield>subtwophasestate</structfield> of <link
+   linkend="catalog-pg-subscription"><structname>pg_subscription</structname>
+   </link> to know the actual two-phase state.
   </para>
  </refsect1>
 
@@ -175,12 +176,14 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
          <para>
           See <xref linkend="sql-createsubscription-notes"/> for details of
           how <literal>copy_data = true</literal> can interact with the
-          <literal>origin</literal> parameter.
+          <link linkend="sql-createsubscription-with-origin">
+          <literal>origin</literal></link> parameter.
          </para>
          <para>
-          See the <link linkend="sql-createsubscription-binary"><literal>binary</literal>
-          option</link> of <command>CREATE SUBSCRIPTION</command> for details
-          about copying pre-existing data in binary format.
+          See the <link linkend="sql-createsubscription-with-binary">
+          <literal>binary</literal></link> parameter of
+          <command>CREATE SUBSCRIPTION</command> for details about copying
+          pre-existing data in binary format.
          </para>
         </listitem>
        </varlistentry>
@@ -214,12 +217,13 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
      <para>
       This clause alters parameters originally set by
       <xref linkend="sql-createsubscription"/>.  See there for more
-      information.  The parameters that can be altered
-      are <literal>slot_name</literal>,
-      <literal>synchronous_commit</literal>,
-      <literal>binary</literal>, <literal>streaming</literal>,
-      <literal>disable_on_error</literal>, and
-      <literal>origin</literal>.
+      information.  The parameters that can be altered are
+      <link linkend="sql-createsubscription-with-slot-name"><literal>slot_name</literal></link>,
+      <link linkend="sql-createsubscription-with-synchronous-commit"><literal>synchronous_commit</literal></link>,
+      <link linkend="sql-createsubscription-with-binary"><literal>binary</literal></link>,
+      <link linkend="sql-createsubscription-with-streaming"><literal>streaming</literal></link>,
+      <link linkend="sql-createsubscription-with-disable-on-error"><literal>disable_on_error</literal></link>,
+      and <link linkend="sql-createsubscription-with-origin"><literal>origin</literal></link>.
      </para>
     </listitem>
    </varlistentry>
@@ -233,14 +237,13 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
       resolved.  By using the <command>ALTER SUBSCRIPTION ... SKIP</command> command,
       the logical replication worker skips all data modification changes within
       the transaction.  This option has no effect on the transactions that are
-      already prepared by enabling <literal>two_phase</literal> on
-      subscriber.
-      After the logical replication worker successfully skips the transaction or
-      finishes a transaction, the LSN (stored in
-      <structname>pg_subscription</structname>.<structfield>subskiplsn</structfield>)
-      is cleared.  See <xref linkend="logical-replication-conflicts"/> for
-      the details of logical replication conflicts.  Using this command requires
-      superuser privilege.
+      already prepared by enabling <link linkend="sql-createsubscription-with-two-phase">
+      <literal>two_phase</literal></link> on the subscriber. After the logical
+      replication worker successfully skips the transaction or finishes a
+      transaction, the LSN (stored in <structname>pg_subscription</structname>.
+      <structfield>subskiplsn</structfield>) is cleared.  See <xref
+      linkend="logical-replication-conflicts"/> for the details of logical
+      replication conflicts. Using this command requires superuser privilege.
      </para>
 
      <para>
diff --git a/doc/src/sgml/ref/create_subscription.sgml b/doc/src/sgml/ref/create_subscription.sgml
index 9d4b9d4e33..a66b8025f3 100644
--- a/doc/src/sgml/ref/create_subscription.sgml
+++ b/doc/src/sgml/ref/create_subscription.sgml
@@ -61,7 +61,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
   <title>Parameters</title>
 
   <variablelist>
-   <varlistentry>
+   <varlistentry id="sql-createsubscription-name">
     <term><replaceable class="parameter">subscription_name</replaceable></term>
     <listitem>
      <para>
@@ -70,7 +70,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
     </listitem>
    </varlistentry>
 
-   <varlistentry>
+   <varlistentry id="sql-createsubscription-connection">
     <term><literal>CONNECTION '<replaceable class="parameter">conninfo</replaceable>'</literal></term>
     <listitem>
      <para>
@@ -81,7 +81,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
     </listitem>
    </varlistentry>
 
-   <varlistentry>
+   <varlistentry id="sql-createsubscription-publication">
     <term><literal>PUBLICATION <replaceable class="parameter">publication_name</replaceable> [, ...]</literal></term>
     <listitem>
      <para>
@@ -90,7 +90,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
     </listitem>
    </varlistentry>
 
-   <varlistentry>
+   <varlistentry id="sql-createsubscription-with">
     <term><literal>WITH ( <replaceable class="parameter">subscription_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] )</literal></term>
     <listitem>
      <para>
@@ -102,7 +102,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
 
       <variablelist>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-connect">
         <term><literal>connect</literal> (<type>boolean</type>)</term>
         <listitem>
          <para>
@@ -129,7 +129,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-create-slot">
         <term><literal>create_slot</literal> (<type>boolean</type>)</term>
         <listitem>
          <para>
@@ -145,7 +145,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-enabled">
         <term><literal>enabled</literal> (<type>boolean</type>)</term>
         <listitem>
          <para>
@@ -156,7 +156,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-slot-name">
         <term><literal>slot_name</literal> (<type>string</type>)</term>
         <listitem>
          <para>
@@ -185,7 +185,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
 
       <variablelist>
 
-       <varlistentry id="sql-createsubscription-binary" xreflabel="binary">
+       <varlistentry id="sql-createsubscription-with-binary">
         <term><literal>binary</literal> (<type>boolean</type>)</term>
         <listitem>
          <para>
@@ -222,7 +222,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-copy-data">
         <term><literal>copy_data</literal> (<type>boolean</type>)</term>
         <listitem>
          <para>
@@ -243,7 +243,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-streaming">
         <term><literal>streaming</literal> (<type>enum</type>)</term>
         <listitem>
          <para>
@@ -271,7 +271,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-synchronous-commit">
         <term><literal>synchronous_commit</literal> (<type>enum</type>)</term>
         <listitem>
          <para>
@@ -303,7 +303,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-two-phase">
         <term><literal>two_phase</literal> (<type>boolean</type>)</term>
         <listitem>
          <para>
@@ -334,7 +334,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-disable-on-error">
         <term><literal>disable_on_error</literal> (<type>boolean</type>)</term>
         <listitem>
          <para>
@@ -346,7 +346,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-origin">
         <term><literal>origin</literal> (<type>string</type>)</term>
         <listitem>
          <para>
diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index d6b1faa804..679fa727cd 100644
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -1458,9 +1458,10 @@ CREATE DATABASE foo WITH TEMPLATE template0;
    truncate the target tables before initiating a new full table copy.  If users
    intend to copy initial data during refresh they must create the slot with
    <literal>two_phase = false</literal>.  After the initial sync, the
-   <literal>two_phase</literal> option will be automatically enabled by the
-   subscriber if the subscription had been originally created with
-   <literal>two_phase = true</literal> option.
+   <link linkend="sql-createsubscription-with-two-phase"><literal>two_phase</literal>
+   </link> option will be automatically enabled by the subscriber if the
+   subscription had been originally created with <literal>two_phase = true</literal>
+   option.
   </para>
  </refsect1>
 
-- 
2.27.0

From e9ca13227ebbb09d494fb8fa9aad6e4596fae830 Mon Sep 17 00:00:00 2001
From: Amit Kapila <akapila@postgresql.org>
Date: Tue, 28 Mar 2023 17:12:22 +0530
Subject: [PATCH v7] Add XML ID attributes to create_subscription.sgml.

Commit ecb696527c added an XML ID attribute to one varlistentry in
create_subscription.sgml. Following 78ee60ed84, this commit adds XML ID
attributes to all varlistentries in create_subscription.sgml.
Additionally, links are added to refer to the subscription options,
enhancing the readability of documents.

Author: Kuroda Hayato
Reviewed-by: Peter Smith, Amit Kapila
Discussion: https://postgr.es/m/TYAPR01MB58667AE04D291924671E2051F5879@TYAPR01MB5866.jpnprd01.prod.outlook.com
---
 doc/src/sgml/config.sgml                  |  5 +--
 doc/src/sgml/logical-replication.sgml     | 41 ++++++++++++++---------
 doc/src/sgml/ref/alter_subscription.sgml  | 37 +++++++++++---------
 doc/src/sgml/ref/create_subscription.sgml | 30 ++++++++---------
 doc/src/sgml/ref/pg_dump.sgml             |  6 ++--
 5 files changed, 67 insertions(+), 52 deletions(-)

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 71730cc52f..f5364daef2 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -11742,8 +11742,9 @@ LOG:  CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1)
         On the publisher side, <varname>logical_replication_mode</varname>
         allows streaming or serializing changes immediately in logical decoding.
         When set to <literal>immediate</literal>, stream each change if the
-        <literal>streaming</literal> option (see optional parameters set by
-        <link linkend="sql-createsubscription"><command>CREATE SUBSCRIPTION</command></link>)
+        <link linkend="sql-createsubscription-with-streaming"><literal>streaming</literal></link>
+        option of
+        <link linkend="sql-createsubscription"><command>CREATE SUBSCRIPTION</command></link>
         is enabled, otherwise, serialize each change.  When set to
         <literal>buffered</literal>, the decoding will stream or serialize
         changes when <varname>logical_decoding_work_mem</varname> is reached.
diff --git a/doc/src/sgml/logical-replication.sgml b/doc/src/sgml/logical-replication.sgml
index 3836d13ad3..6358c5da05 100644
--- a/doc/src/sgml/logical-replication.sgml
+++ b/doc/src/sgml/logical-replication.sgml
@@ -252,8 +252,9 @@
    additional columns not provided by the published table.  Any such columns
    will be filled with the default value as specified in the definition of the
    target table. However, logical replication in binary format is more
-   restrictive. See the <link linkend="sql-createsubscription-binary"><literal>binary</literal>
-   option</link> of <command>CREATE SUBSCRIPTION</command> for details.
+   restrictive. See the
+   <link linkend="sql-createsubscription-with-binary"><literal>binary</literal></link>
+   option of <command>CREATE SUBSCRIPTION</command> for details.
   </para>
 
   <sect2 id="logical-replication-subscription-slot">
@@ -587,7 +588,9 @@ ALTER SUBSCRIPTION
 
    <para>
     Example 2: Where the subscription says <literal>connect = false</literal>,
-    but also specifies the <literal>slot_name</literal>
+    but also specifies the
+    <link linkend="sql-createsubscription-with-slot-name"><literal>slot_name</literal></link>
+    option.
     <itemizedlist>
      <listitem>
       <para>
@@ -704,9 +707,10 @@ ALTER SUBSCRIPTION
     If the row filter evaluates to <literal>false</literal> or <literal>NULL</literal>
     then the row is not replicated. The <literal>WHERE</literal> clause expression
     is evaluated with the same role used for the replication connection (i.e.
-    the role specified in the <literal>CONNECTION</literal> clause of the
-    <xref linkend="sql-createsubscription"/>). Row filters have no effect for
-    <command>TRUNCATE</command> command.
+    the role specified in the
+    <link linkend="sql-createsubscription-connection"><literal>CONNECTION</literal></link>
+    clause of the <xref linkend="sql-createsubscription"/>). Row filters have
+    no effect for <command>TRUNCATE</command> command.
    </para>
 
   </sect2>
@@ -1500,9 +1504,10 @@ CONTEXT:  processing remote data for replication origin "pg_16395" during "INSER
    <function>pg_replication_origin_advance()</function></link> function.
    Before using this function, the subscription needs to be disabled temporarily
    either by <command>ALTER SUBSCRIPTION ... DISABLE</command> or, the
-   subscription can be used with the <literal>disable_on_error</literal> option.
-   Then, you can use <function>pg_replication_origin_advance()</function> function
-   with the <parameter>node_name</parameter> (i.e., <literal>pg_16395</literal>)
+   subscription can be used with the
+   <link linkend="sql-createsubscription-with-disable-on-error"><literal>disable_on_error</literal></link>
+   option. Then, you can use <function>pg_replication_origin_advance()</function>
+   function with the <parameter>node_name</parameter> (i.e., <literal>pg_16395</literal>)
    and the next LSN of the finish LSN (i.e., 0/14C0379).  The current position of
    origins can be seen in the <link linkend="view-pg-replication-origin-status">
    <structname>pg_replication_origin_status</structname></link> system view.
@@ -1512,11 +1517,13 @@ CONTEXT:  processing remote data for replication origin "pg_16395" during "INSER
   </para>
 
   <para>
-   When the streaming mode is <literal>parallel</literal>, the finish LSN of
-   failed transactions may not be logged. In that case, it may be necessary to
-   change the streaming mode to <literal>on</literal> or <literal>off</literal> and
-   cause the same conflicts again so the finish LSN of the failed transaction will
-   be written to the server log. For the usage of finish LSN, please refer to <link
+   When the
+   <link linkend="sql-createsubscription-with-streaming"><literal>streaming</literal></link>
+   mode is <literal>parallel</literal>, the finish LSN of failed transactions
+   may not be logged. In that case, it may be necessary to change the streaming
+   mode to <literal>on</literal> or <literal>off</literal> and cause the same
+   conflicts again so the finish LSN of the failed transaction will be written
+   to the server log. For the usage of finish LSN, please refer to <link
    linkend="sql-altersubscription"><command>ALTER SUBSCRIPTION ...
    SKIP</command></link>.
   </para>
@@ -1701,8 +1708,10 @@ CONTEXT:  processing remote data for replication origin "pg_16395" during "INSER
    subscription.  A disabled subscription or a crashed subscription will have
    zero rows in this view.  If the initial data synchronization of any
    table is in progress, there will be additional workers for the tables
-   being synchronized. Moreover, if the streaming transaction is applied in
-   parallel, there may be additional parallel apply workers.
+   being synchronized. Moreover, if the
+   <link linkend="sql-createsubscription-with-streaming"><literal>streaming</literal></link>
+   transaction is applied in parallel, there may be additional parallel apply
+   workers.
   </para>
  </sect1>
 
diff --git a/doc/src/sgml/ref/alter_subscription.sgml b/doc/src/sgml/ref/alter_subscription.sgml
index e92346edef..9735a82206 100644
--- a/doc/src/sgml/ref/alter_subscription.sgml
+++ b/doc/src/sgml/ref/alter_subscription.sgml
@@ -71,10 +71,11 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
    executed inside a transaction block.
 
    These commands also cannot be executed when the subscription has
-   <literal>two_phase</literal> commit enabled,
-   unless <literal>copy_data</literal> is <literal>false</literal>.
-   See column <structfield>subtwophasestate</structfield> of
-   <link linkend="catalog-pg-subscription"><structname>pg_subscription</structname></link>
+   <link linkend="sql-createsubscription-with-two-phase"><literal>two_phase</literal></link>
+   commit enabled, unless
+   <link linkend="sql-createsubscription-with-copy-data"><literal>copy_data</literal></link>
+   is <literal>false</literal>. See column <structfield>subtwophasestate</structfield>
+   of <link linkend="catalog-pg-subscription"><structname>pg_subscription</structname></link>
    to know the actual two-phase state.
   </para>
  </refsect1>
@@ -175,12 +176,14 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
          <para>
           See <xref linkend="sql-createsubscription-notes"/> for details of
           how <literal>copy_data = true</literal> can interact with the
-          <literal>origin</literal> parameter.
+          <link linkend="sql-createsubscription-with-origin"><literal>origin</literal></link>
+          parameter.
          </para>
          <para>
-          See the <link linkend="sql-createsubscription-binary"><literal>binary</literal>
-          option</link> of <command>CREATE SUBSCRIPTION</command> for details
-          about copying pre-existing data in binary format.
+          See the
+          <link linkend="sql-createsubscription-with-binary"><literal>binary</literal></link>
+          parameter of <command>CREATE SUBSCRIPTION</command> for details about
+          copying pre-existing data in binary format.
          </para>
         </listitem>
        </varlistentry>
@@ -214,12 +217,13 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
      <para>
       This clause alters parameters originally set by
       <xref linkend="sql-createsubscription"/>.  See there for more
-      information.  The parameters that can be altered
-      are <literal>slot_name</literal>,
-      <literal>synchronous_commit</literal>,
-      <literal>binary</literal>, <literal>streaming</literal>,
-      <literal>disable_on_error</literal>, and
-      <literal>origin</literal>.
+      information.  The parameters that can be altered are
+      <link linkend="sql-createsubscription-with-slot-name"><literal>slot_name</literal></link>,
+      <link linkend="sql-createsubscription-with-synchronous-commit"><literal>synchronous_commit</literal></link>,
+      <link linkend="sql-createsubscription-with-binary"><literal>binary</literal></link>,
+      <link linkend="sql-createsubscription-with-streaming"><literal>streaming</literal></link>,
+      <link linkend="sql-createsubscription-with-disable-on-error"><literal>disable_on_error</literal></link>,
+      and <link linkend="sql-createsubscription-with-origin"><literal>origin</literal></link>.
      </para>
     </listitem>
    </varlistentry>
@@ -233,8 +237,9 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
       resolved.  By using the <command>ALTER SUBSCRIPTION ... SKIP</command> command,
       the logical replication worker skips all data modification changes within
       the transaction.  This option has no effect on the transactions that are
-      already prepared by enabling <literal>two_phase</literal> on
-      subscriber.
+      already prepared by enabling
+      <link linkend="sql-createsubscription-with-two-phase"><literal>two_phase</literal></link>
+      on the subscriber.
       After the logical replication worker successfully skips the transaction or
       finishes a transaction, the LSN (stored in
       <structname>pg_subscription</structname>.<structfield>subskiplsn</structfield>)
diff --git a/doc/src/sgml/ref/create_subscription.sgml b/doc/src/sgml/ref/create_subscription.sgml
index 9d4b9d4e33..a66b8025f3 100644
--- a/doc/src/sgml/ref/create_subscription.sgml
+++ b/doc/src/sgml/ref/create_subscription.sgml
@@ -61,7 +61,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
   <title>Parameters</title>
 
   <variablelist>
-   <varlistentry>
+   <varlistentry id="sql-createsubscription-name">
     <term><replaceable class="parameter">subscription_name</replaceable></term>
     <listitem>
      <para>
@@ -70,7 +70,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
     </listitem>
    </varlistentry>
 
-   <varlistentry>
+   <varlistentry id="sql-createsubscription-connection">
     <term><literal>CONNECTION '<replaceable class="parameter">conninfo</replaceable>'</literal></term>
     <listitem>
      <para>
@@ -81,7 +81,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
     </listitem>
    </varlistentry>
 
-   <varlistentry>
+   <varlistentry id="sql-createsubscription-publication">
     <term><literal>PUBLICATION <replaceable class="parameter">publication_name</replaceable> [, ...]</literal></term>
     <listitem>
      <para>
@@ -90,7 +90,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
     </listitem>
    </varlistentry>
 
-   <varlistentry>
+   <varlistentry id="sql-createsubscription-with">
     <term><literal>WITH ( <replaceable class="parameter">subscription_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] )</literal></term>
     <listitem>
      <para>
@@ -102,7 +102,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
 
       <variablelist>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-connect">
         <term><literal>connect</literal> (<type>boolean</type>)</term>
         <listitem>
          <para>
@@ -129,7 +129,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-create-slot">
         <term><literal>create_slot</literal> (<type>boolean</type>)</term>
         <listitem>
          <para>
@@ -145,7 +145,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-enabled">
         <term><literal>enabled</literal> (<type>boolean</type>)</term>
         <listitem>
          <para>
@@ -156,7 +156,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-slot-name">
         <term><literal>slot_name</literal> (<type>string</type>)</term>
         <listitem>
          <para>
@@ -185,7 +185,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
 
       <variablelist>
 
-       <varlistentry id="sql-createsubscription-binary" xreflabel="binary">
+       <varlistentry id="sql-createsubscription-with-binary">
         <term><literal>binary</literal> (<type>boolean</type>)</term>
         <listitem>
          <para>
@@ -222,7 +222,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-copy-data">
         <term><literal>copy_data</literal> (<type>boolean</type>)</term>
         <listitem>
          <para>
@@ -243,7 +243,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-streaming">
         <term><literal>streaming</literal> (<type>enum</type>)</term>
         <listitem>
          <para>
@@ -271,7 +271,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-synchronous-commit">
         <term><literal>synchronous_commit</literal> (<type>enum</type>)</term>
         <listitem>
          <para>
@@ -303,7 +303,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-two-phase">
         <term><literal>two_phase</literal> (<type>boolean</type>)</term>
         <listitem>
          <para>
@@ -334,7 +334,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-disable-on-error">
         <term><literal>disable_on_error</literal> (<type>boolean</type>)</term>
         <listitem>
          <para>
@@ -346,7 +346,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-with-origin">
         <term><literal>origin</literal> (<type>string</type>)</term>
         <listitem>
          <para>
diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index d6b1faa804..77299878e0 100644
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -1458,9 +1458,9 @@ CREATE DATABASE foo WITH TEMPLATE template0;
    truncate the target tables before initiating a new full table copy.  If users
    intend to copy initial data during refresh they must create the slot with
    <literal>two_phase = false</literal>.  After the initial sync, the
-   <literal>two_phase</literal> option will be automatically enabled by the
-   subscriber if the subscription had been originally created with
-   <literal>two_phase = true</literal> option.
+   <link linkend="sql-createsubscription-with-two-phase"><literal>two_phase</literal></link>
+   option will be automatically enabled by the subscriber if the subscription
+   had been originally created with <literal>two_phase = true</literal> option.
   </para>
  </refsect1>
 
-- 
2.28.0.windows.1