From aa8547a219d3749cffbda4da8976fc421dfcd5c2 Mon Sep 17 00:00:00 2001
From: Ian Barwick <ian@2ndquadrant.com>
Date: Thu, 17 Jan 2019 10:42:53 +0900
Subject: [PATCH] Improve "witness register" documentation, help and logging

Make it clearer that a) the primary server's hostname is required,
and b) how to provide it.

Based on feedback provided in GitHub #529.
---
 doc/repmgr-witness-register.sgml | 17 +++++++++++------
 repmgr-action-witness.c          |  6 ++++--
 repmgr-client.c                  |  4 ++--
 3 files changed, 17 insertions(+), 10 deletions(-)

diff --git a/doc/repmgr-witness-register.sgml b/doc/repmgr-witness-register.sgml
index 84bde114..d6d7a676 100644
--- a/doc/repmgr-witness-register.sgml
+++ b/doc/repmgr-witness-register.sgml
@@ -23,14 +23,19 @@
       use of the witness server with <application>repmgrd</application>.
     </para>
     <para>
-      When executing <command>repmgr witness register</command>, connection information
-      for the cluster primary server must also be provided. &repmgr; will automatically
-      use the <varname>user</varname> and <varname>dbname</varname> values defined
-      in the <varname>conninfo</varname> string defined in the  witness node's
-      <filename>repmgr.conf</filename>, if these are not explicitly provided.
+      When executing <command>repmgr witness register</command>, database connection
+      information for the cluster primary server must also be provided.
     </para>
     <para>
-      Execute with the <literal>--dry-run</literal> option to check what would happen
+      In most cases it's only necessary to provide the primary's hostname with
+      the <option>-h</option>/<option>--hostname</option> option; &repmgr; will
+      automatically use the <varname>user</varname> and <varname>dbname</varname>
+      values defined in the <varname>conninfo</varname> string defined in the
+      witness node's <filename>repmgr.conf</filename>, unless these are explicitly
+      provided as command line options.
+    </para>
+    <para>
+      Execute with the <option>--dry-run</option> option to check what would happen
       without actually registering the witness server.
     </para>
   </refsect1>
diff --git a/repmgr-action-witness.c b/repmgr-action-witness.c
index 16597e55..e487d2e7 100644
--- a/repmgr-action-witness.c
+++ b/repmgr-action-witness.c
@@ -484,13 +484,15 @@ void do_witness_help(void)
 	printf(_("Usage:\n"));
 	printf(_("    %s [OPTIONS] witness register\n"), progname());
 	printf(_("    %s [OPTIONS] witness unregister\n"), progname());
-
+	puts("");
 	printf(_("WITNESS REGISTER\n"));
 	puts("");
 	printf(_("  \"witness register\" registers a witness node.\n"));
 	puts("");
-	printf(_("  Requires provision of connection information for the primary\n"));
+	printf(_("  Requires provision of connection information for the primary node,\n"));
+	printf(_("  typically usually just the hostname.\n"));
 	puts("");
+	printf(_("  -h/--hostname            hostname of the primary node\n"));
 	printf(_("  --dry-run                check prerequisites but don't make any changes\n"));
 	printf(_("  -F, --force              overwrite an existing node record\n"));
 	puts("");
diff --git a/repmgr-client.c b/repmgr-client.c
index 2e31f7c3..565af405 100644
--- a/repmgr-client.c
+++ b/repmgr-client.c
@@ -1409,7 +1409,7 @@ check_cli_parameters(const int action)
 					if (!runtime_options.host_param_provided)
 					{
 						item_list_append_format(&cli_errors,
-												_("host name for the source node must be provided when executing %s"),
+												_("host name for the source node must be provided with -h/--hostname when executing %s"),
 												action_name(action));
 					}
 
@@ -1466,7 +1466,7 @@ check_cli_parameters(const int action)
 				if (!runtime_options.host_param_provided)
 				{
 					item_list_append_format(&cli_errors,
-											_("host name for the source node must be provided when executing %s"),
+											_("host name for the source node must be provided with -h/--hostname when executing %s"),
 											action_name(action));
 				}
 			}