From d362cb5dcabce24e13572aa8a67f1dfa9c2b6b60 Mon Sep 17 00:00:00 2001
From: Tatsuo Ishii <ishii@sraoss.co.jp>
Date: Tue, 28 Jul 2020 11:36:11 +0900
Subject: [PATCH] Doc: clarify what the command actual does.

Discussion: https://www.pgpool.net/pipermail/pgpool-hackers/2020-July/003744.html
Reviewed-by: Bo Peng
---
 doc.ja/src/sgml/ref/pcp_promote_node.sgml | 36 +++++++++++++++++---
 doc/src/sgml/ref/pcp_promote_node.sgml    | 41 +++++++++++++++++++++++
 2 files changed, 72 insertions(+), 5 deletions(-)

diff --git a/doc.ja/src/sgml/ref/pcp_promote_node.sgml b/doc.ja/src/sgml/ref/pcp_promote_node.sgml
index 80445149f..519a4efee 100644
--- a/doc.ja/src/sgml/ref/pcp_promote_node.sgml
+++ b/doc.ja/src/sgml/ref/pcp_promote_node.sgml
@@ -39,14 +39,40 @@ Pgpool-II documentation
   <title>説明</title>
   <para>
    <command>pcp_promote_node</command>
-   <!--
-   promotes the given node as new master to Pgpool-II. In master/slave streaming replication only. Please note that this command does not actually promote standby PostgreSQL backend: it just changes the internal status of Pgpool-II and trigger failover and users have to promote standby PostgreSQL outside Pgpool-II.
-   -->
    は <productname>Pgpool-II</productname> のノードをマスターに昇格させます。
    これは、マスタースレーブモードで ストリーミングレプリケーション構成の場合のみ使用できます。
    このコマンドは実際に <productname>PostgreSQL</productname> のスタンバイサーバを昇格するわけではないことに注意してください。
-   単に <productname>Pgpool-II</productname> の内部ステータスを変更し、フェイルオーバするだけです。
-   ですので、ユーザはこのコマンドを使う際には自分で <productname>PostgreSQL</productname> のスタンバイを昇格させるようにしてください。
+   単に <productname>Pgpool-II</productname> の内部ステータスを変更するだけです。
+   ですから、ユーザはこのコマンドを使う際には自分で <productname>PostgreSQL</productname> のスタンバイを昇格させるようにしてください。
+  </para>
+  <para>
+   <command>pcp_promote_node</command>は、起動された後以下を行います。
+   <xref linkend="guc-follow-master-command">が設定されている場合はそれも起動されるので、十分な注意が必要です。
+   通常は<xref linkend="guc-follow-master-command">を無効にしてからこのコマンドを実行することをお勧めします。
+
+   <orderedlist>
+
+    <listitem>
+     <para>
+      指定されたスタンバイ<productname>PostgreSQL</productname>のステータスをstandbyからprimaryに変更します。
+      これは<productname>Pgpool-II</productname> の内部ステータスを変更するだけで、実際に<productname>PostgreSQL</productname> のスタンバイサーバを昇格するわけではありません。
+     </para>
+    </listitem>     
+
+    <listitem>
+     <para>
+      引数で指定された以外の<productname>PostgreSQL</productname>ノードのステータスをdownに変更します。
+      これは<productname>Pgpool-II</productname> の内部ステータスを変更するだけで、実際に<productname>PostgreSQL</productname>のスタンバイサーバをダウンさせるわけではありません。
+     </para>
+    </listitem>     
+
+    <listitem>
+     <para>
+      <xref linkend="guc-follow-master-command">が設定されている場合は、2でダウンさせた<productname>PostgreSQL</productname>ノードに対して<xref linkend="guc-follow-master-command">を実行します。
+     </para>
+    </listitem>     
+
+   </orderedlist>
   </para>
  </refsect1>
 
diff --git a/doc/src/sgml/ref/pcp_promote_node.sgml b/doc/src/sgml/ref/pcp_promote_node.sgml
index 1f6d423d0..537f18aac 100644
--- a/doc/src/sgml/ref/pcp_promote_node.sgml
+++ b/doc/src/sgml/ref/pcp_promote_node.sgml
@@ -35,6 +35,47 @@ Pgpool-II documentation
    <command>pcp_promote_node</command>
    promotes the given node as new master to Pgpool-II. In master/slave streaming replication only. Please note that this command does not actually promote standby PostgreSQL backend: it just changes the internal status of Pgpool-II and trigger failover and users have to promote standby PostgreSQL outside Pgpool-II.
   </para>
+
+  <para>
+   <command>pcp_promote_node</command> executes followings.  Please be
+   warned that if <xref linkend="guc-follow-master-command"> is set,
+   the command will be executed.  It is a standard advice that you
+   disable <xref linkend="guc-follow-master-command"> before executing
+   this command.
+
+   <orderedlist>
+
+    <listitem>
+     <para>
+      Change the status of standby
+      <productname>PostgreSQL</productname> from standby to
+      primary. It just changes the internal status of Pgpool-II and it
+      does not actually promote <productname>PostgreSQL</productname>
+      standby server.
+     </para>
+    </listitem>     
+
+    <listitem>
+     <para>
+      Change the status of <productname>PostgreSQL</productname> node
+      which is not specified by this command's argument to down.  It
+      just changes the internal status of Pgpool-II and it does not
+      actually make <productname>PostgreSQL</productname> standby
+      server down.
+     </para>
+    </listitem>     
+
+    <listitem>
+     <para>
+      If <xref linkend="guc-follow-master-command"> is set, execute
+      <xref linkend="guc-follow-master-command"> against
+      <productname>PostgreSQL</productname>.
+     </para>
+    </listitem>     
+
+   </orderedlist>
+  </para>
+
  </refsect1>
 
  <refsect1>
-- 
2.39.5