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

5 files changed, 67 insertions, 52 deletions

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index bda0da2dc8..fcb53c6997 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -11768,8 +11768,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>