DOC: pg-shardman doc improvement

Author: Liudmila Mantrova

doc/src/sgml/pg_shardman.sgml

@@ -221,7 +221,7 @@
     replication, which can cause data inconsistencies if a node fails
     permanently. A part of a distributed transaction might get lost and cause
     a non-atomic result if the coordinator has prepared the transaction
-    everywhere, started commiting it, but one of the nodes failed before
+    everywhere, started committing it, but one of the nodes failed before
     committing the transaction on a replica.
   </para>
 
@@ -973,7 +973,7 @@ manually excluded from the cluster, as follows:
     <para>
     Run the following command to to exclude the node from the cluster:
 <programlisting>
-select shardman.rm_node(${failed_node_id}, force => true);
+SELECT shardman.rm_node(${failed_node_id}, force => true);
 </programlisting>
     If redundancy level is greater than zero, <filename>pg_shardman</filename> tries to replace
     primary shards stored on the excluded node with their replicas. The most advanced replica
@@ -1073,11 +1073,11 @@ iterations are the same, the deadlock is confirmed.
 </para>
 
 <para>
-<filename>pg_shardman</filename> tries to resolve reported deadlocks
-by canceling one or more backends involved in the deadlock loop using
-the <function>pg_cancel_backend</function> function. This function tries
-to cancel the current query, without terminating the backend. The affected backend is
-randomly chosen within the deadlock loop.
+<filename>pg_shardman</filename> tries to resolve reported deadlocks by
+canceling one or more backends involved in the deadlock loop. It invokes the
+<function>pg_cancel_backend</function> function that tries to
+cancel the current query, without terminating the backend. The affected
+backend is randomly chosen within the deadlock loop.
 </para>
 
 <para>
@@ -1152,10 +1152,9 @@ excludes this node from the cluster, as follows:
      </term>
      <listitem>
       <para>
-       When set to <literal>on</literal>, <filename>pg_shardman</filename>
+       When this parameter is set to <literal>on</literal>, <filename>pg_shardman</filename>
        adds replicas to the list of <xref linkend="guc-synchronous-standby-names">,
-       enabling synchronous replication. This parameter should not be changed
-       if any replicas exist.
+       enabling synchronous replication.
       </para>
       <para>
        Default: <literal>off</literal>
@@ -1827,9 +1826,8 @@ excludes this node from the cluster, as follows:
       <para>
         Monitors the cluster state to detect distributed deadlocks and node failures.
         If a distributed deadlock is detected, <filename>pg_shardman</filename>
-        tries to resolve the deadlock by canceling one or more queries on the affected backend
-        using the <function>pg_cancel_backend</function> function. For details,
-        see <xref linkend="shardman-detecting-deadlocks-and-failed-nodes">.
+        tries to resolve the deadlock by canceling one or more queries on the affected
+        backend. For details, see <xref linkend="shardman-detecting-deadlocks-and-failed-nodes">.
         This function is redirected to the shardlord if launched on a worker node.
       </para>
       <para>Arguments:
@@ -1898,7 +1896,8 @@ excludes this node from the cluster, as follows:
         Since <filename>pg_shardman</filename> does not control WAL recycling,
         <function>shardman.recover_xacts</function> uses clog to check
         the transaction status. Though unlikely, <function>shardman.recover_xacts</function>
-        may fail to get the transaction status and resolve the transaction.
+        may fail to get the transaction status and resolve the transaction
+        and it has to be resolved manually.
       </para>
         </listitem>
     </varlistentry>
@@ -1917,17 +1916,16 @@ excludes this node from the cluster, as follows:
         Removes all publications, subscriptions, replication slots, foreign
         servers, and user mappings created on the worker node by
         <filename>pg_shardman</filename>. <productname>&project;</productname>
-        forbids dropping replication slots with active connection. If
+        forbids dropping replication slots with active connections. If
         <parameter>force</parameter> is <literal>true</literal>,
         <filename>pg_shardman</filename> tries to kill <acronym>WAL</acronym> senders before
-        dropping the slots. This command does not affect the data
-        stored on this node.
+        dropping the slots, without affecting the data stored on this node. Once this transaction commits, the
+        <varname>synchronous_standby_names</varname> variable is set to an empty string. It is a
+        non-transactional action, so there is a very small chance it won't be
+        completed.
       </para>
       <para>
-        Also, immediately after transaction commit
-        set <varname>synchronous_standby_names</varname> variable to an empty string. It is a
-        non-transactional action and there is a very small chance it won't be
-        completed. You probably want to run it before <command>DROP EXTENSION pg_shardman</command>.
+        You may want to run this function before <command>DROP EXTENSION pg_shardman</command>.
       </para>
         </listitem>
     </varlistentry>