From d9f25b868dc32d748f714c77ea3771ff361958ad Mon Sep 17 00:00:00 2001
From: Tatsuo Ishii <ishii@sraoss.co.jp>
Date: Sat, 20 Feb 2021 09:45:16 +0900
Subject: [PATCH] Doc: enhance pcp_detach_node manual.

Add more detailed description when the command is executed.
---
 doc.ja/src/sgml/ref/pcp_detach_node.sgml | 16 +++++++++++-----
 doc/src/sgml/ref/pcp_detach_node.sgml    | 24 +++++++++++++++++++++---
 2 files changed, 32 insertions(+), 8 deletions(-)

diff --git a/doc.ja/src/sgml/ref/pcp_detach_node.sgml b/doc.ja/src/sgml/ref/pcp_detach_node.sgml
index 89b5a0844..c066cbf60 100644
--- a/doc.ja/src/sgml/ref/pcp_detach_node.sgml
+++ b/doc.ja/src/sgml/ref/pcp_detach_node.sgml
@@ -38,11 +38,17 @@ Pgpool-II documentation
   -->
   <title>説明</title>
   <para>
-   <command>pcp_detach_node</command>
-   <!--
-   detaches the given node from Pgpool-II. Exisiting connections to Pgpool-II are forced to be disconnected.
-   -->
-   は <productname>Pgpool-II</productname> のノードを切り離します。すでに <productname>Pgpool-II</productname> に接続しているセッションは強制的に切断されます。
+   <command>pcp_detach_node</command> は <productname>Pgpool-II</productname> のノードを切り離します。
+   <xref linkend="guc-failover-command"> あるいは <xref linkend="guc-follow-primary-command">が指定されていれば、それらも実行されます。
+   すでに <productname>Pgpool-II</productname> に接続しているセッションは強制的に切断されます。
+  </para>
+  <para>
+   <command>pcp_detach_node</command>は単にノードを切り離すだけで、そのノードで背後で稼働しているバックエンドには触りません。
+   このコマンドは、管理者が<productname>PostgreSQL</productname>ノードを保守する際に有用です。
+   管理者は好きなだけそのバックエンドを停止したり起動できます。
+  </para>
+  <para>
+   切り離したノードは、バックエンドを停止した上で<xref linkend="pcp-recovery-node">で復帰させるのが安全ですが、レプリケーション遅延がない（もしくは後でレプリケーション遅延を回復できる）ことが確実で、ノードの役割(プライマリ/スタンバイ)の変更を伴わないことが確実なら、<xref linkend="pcp-attach-node">で復帰させることもできます。
   </para>
  </refsect1>
 
diff --git a/doc/src/sgml/ref/pcp_detach_node.sgml b/doc/src/sgml/ref/pcp_detach_node.sgml
index cf269db6f..29661b52f 100644
--- a/doc/src/sgml/ref/pcp_detach_node.sgml
+++ b/doc/src/sgml/ref/pcp_detach_node.sgml
@@ -17,7 +17,7 @@ Pgpool-II documentation
  <refnamediv>
   <refname>pcp_detach_node</refname>
   <refpurpose>
-   detaches the given node from Pgpool-II. Existing connections to Pgpool-II are forced to be disconnected.</refpurpose>
+   detaches the given node from Pgpool-II. Exisiting connections to Pgpool-II are forced to be disconnected.</refpurpose>
  </refnamediv>
 
  <refsynopsisdiv>
@@ -32,8 +32,26 @@ Pgpool-II documentation
  <refsect1 id="R1-PCP-DETACH-NODE-1">
   <title>Description</title>
   <para>
-   <command>pcp_detach_node</command>
-   detaches the given node from Pgpool-II. Existing connections to Pgpool-II are forced to be disconnected.
+   <command>pcp_detach_node</command> detaches the given node from
+   <productname>Pgpool-II</productname>. If <xref
+   linkend="guc-failover-command"> and/or <xref
+   linkend="guc-follow-primary-command"> are specified, they are
+   executed too. Existing connections to
+   <productname>Pgpool-II</productname> are forced to be disconnected.
+  </para>
+  <para>
+   <command>pcp_detach_node</command> just detaches the node, and does
+   not touch running backend behind the node. This command is useful
+   when admin needs to maintain the
+   <productname>PostgreSQL</productname> node. He/she can shutdown or
+   stop the backend as many times as he/she wants.
+  </para>
+  <para>
+   The safest way to re-attach the detached node is, stopping the
+    backend and apply <xref linkend="pcp-recovery-node">. However if
+    you are sure that there's no replication delay (or the delay will
+    be recovered later on) and the role of the node (primary/standby)
+    will not be changed, you can use <xref linkend="pcp-attach-node">.
   </para>
  </refsect1>
 
-- 
2.39.5