Reorder pg_ctl promote after pg_ctl status

Since start/stop/restart/reload/status is a kind of standard command
set, it seems odd to insert the special-purpose "promote" in between
the closely related "restart" and "reload".  So put it after "status"
in code and documentation.

Put the documentation of the -U option in some sensible place.

Rewrite the synopsis sentence in help and documentation to make it
less of a growing mouthful.

doc/src/sgml/ref/pg_ctl-ref.sgml

@@ -12,7 +12,7 @@ PostgreSQL documentation
 
  <refnamediv>
   <refname>pg_ctl</refname>
-  <refpurpose>initialize, start, stop, or restart a <productname>PostgreSQL</productname> server</refpurpose>
+  <refpurpose>initialize, start, stop, or control a <productname>PostgreSQL</productname> server</refpurpose>
  </refnamediv>
 
  <indexterm zone="app-pg-ctl">
@@ -75,13 +75,6 @@ PostgreSQL documentation
    <arg>-o <replaceable>options</replaceable></arg>
   </cmdsynopsis>
 
-  <cmdsynopsis>
-   <command>pg_ctl</command>
-   <arg choice="plain">promote</arg>
-   <arg>-s</arg>
-   <arg>-D <replaceable>datadir</replaceable></arg>
-  </cmdsynopsis>
-
   <cmdsynopsis>
    <command>pg_ctl</command>
    <arg choice="plain">reload</arg>
@@ -95,6 +88,13 @@ PostgreSQL documentation
    <arg>-D <replaceable>datadir</replaceable></arg>
   </cmdsynopsis>
 
+  <cmdsynopsis>
+   <command>pg_ctl</command>
+   <arg choice="plain">promote</arg>
+   <arg>-s</arg>
+   <arg>-D <replaceable>datadir</replaceable></arg>
+  </cmdsynopsis>
+
   <cmdsynopsis>
    <command>pg_ctl</command>
    <arg choice="plain">kill</arg>
@@ -190,12 +190,6 @@ PostgreSQL documentation
    command-line options.
   </para>
 
-  <para>
-   In <option>promote</option> mode, the standby server that is
-   running in the specified data directory is commanded to exit
-   recovery and begin read-write operations.
-  </para>
-
   <para>
    <option>reload</option> mode simply sends the
    <command>postgres</command> process a <systemitem>SIGHUP</>
@@ -213,6 +207,12 @@ PostgreSQL documentation
    displayed.
   </para>
 
+  <para>
+   In <option>promote</option> mode, the standby server that is
+   running in the specified data directory is commanded to exit
+   recovery and begin read-write operations.
+  </para>
+
   <para>
    <option>kill</option> mode allows you to send a signal to a specified
     process.  This is particularly valuable for <productname>Microsoft Windows</>
@@ -396,16 +396,6 @@ PostgreSQL documentation
      </listitem>
     </varlistentry>
 
-    <varlistentry>
-     <term><option>-U <replaceable class="parameter">username</replaceable></option></term>
-     <listitem>
-      <para>
-       User name for the user to start the service. For domain users, use the
-       format <literal>DOMAIN\username</literal>.
-      </para>
-     </listitem>
-    </varlistentry>
-
     <varlistentry>
      <term><option>-P <replaceable class="parameter">password</replaceable></option></term>
      <listitem>
@@ -426,6 +416,16 @@ PostgreSQL documentation
       </para>
      </listitem>
     </varlistentry>
+
+    <varlistentry>
+     <term><option>-U <replaceable class="parameter">username</replaceable></option></term>
+     <listitem>
+      <para>
+       User name for the user to start the service. For domain users, use the
+       format <literal>DOMAIN\username</literal>.
+      </para>
+     </listitem>
+    </varlistentry>
    </variablelist>
   </refsect2>
 

src/bin/pg_ctl/pg_ctl.c

@@ -62,9 +62,9 @@ typedef enum
 	START_COMMAND,
 	STOP_COMMAND,
 	RESTART_COMMAND,
-	PROMOTE_COMMAND,
 	RELOAD_COMMAND,
 	STATUS_COMMAND,
+	PROMOTE_COMMAND,
 	KILL_COMMAND,
 	REGISTER_COMMAND,
 	UNREGISTER_COMMAND,
@@ -126,9 +126,9 @@ static void do_init(void);
 static void do_start(void);
 static void do_stop(void);
 static void do_restart(void);
-static void do_promote(void);
 static void do_reload(void);
 static void do_status(void);
+static void do_promote(void);
 static void do_kill(pgpid_t pid);
 static void print_msg(const char *msg);
 
@@ -922,7 +922,7 @@ do_stop(void)
 
 
 /*
- *	restart/promote/reload routines
+ *	restart/reload routines
  */
 
 static void
@@ -1018,6 +1018,43 @@ do_restart(void)
 	do_start();
 }
 
+static void
+do_reload(void)
+{
+	pgpid_t		pid;
+
+	pid = get_pgpid();
+	if (pid == 0)				/* no pid file */
+	{
+		write_stderr(_("%s: PID file \"%s\" does not exist\n"), progname, pid_file);
+		write_stderr(_("Is server running?\n"));
+		exit(1);
+	}
+	else if (pid < 0)			/* standalone backend, not postmaster */
+	{
+		pid = -pid;
+		write_stderr(_("%s: cannot reload server; "
+					   "single-user server is running (PID: %ld)\n"),
+					 progname, pid);
+		write_stderr(_("Please terminate the single-user server and try again.\n"));
+		exit(1);
+	}
+
+	if (kill((pid_t) pid, sig) != 0)
+	{
+		write_stderr(_("%s: could not send reload signal (PID: %ld): %s\n"),
+					 progname, pid, strerror(errno));
+		exit(1);
+	}
+
+	print_msg(_("server signaled\n"));
+}
+
+
+/*
+ * promote
+ */
+
 static void
 do_promote(void)
 {
@@ -1079,38 +1116,6 @@ do_promote(void)
 }
 
 
-static void
-do_reload(void)
-{
-	pgpid_t		pid;
-
-	pid = get_pgpid();
-	if (pid == 0)				/* no pid file */
-	{
-		write_stderr(_("%s: PID file \"%s\" does not exist\n"), progname, pid_file);
-		write_stderr(_("Is server running?\n"));
-		exit(1);
-	}
-	else if (pid < 0)			/* standalone backend, not postmaster */
-	{
-		pid = -pid;
-		write_stderr(_("%s: cannot reload server; "
-					   "single-user server is running (PID: %ld)\n"),
-					 progname, pid);
-		write_stderr(_("Please terminate the single-user server and try again.\n"));
-		exit(1);
-	}
-
-	if (kill((pid_t) pid, sig) != 0)
-	{
-		write_stderr(_("%s: could not send reload signal (PID: %ld): %s\n"),
-					 progname, pid, strerror(errno));
-		exit(1);
-	}
-
-	print_msg(_("server signaled\n"));
-}
-
 /*
  *	utility routines
  */
@@ -1732,17 +1737,16 @@ do_advice(void)
 static void
 do_help(void)
 {
-	printf(_("%s is a utility to start, stop, restart, promote, reload configuration files,\n"
+	printf(_("%s is a utility to initialize, start, stop, or control a PostgreSQL server.\n\n"), progname);
-			 "report the status of a PostgreSQL server, or signal a PostgreSQL process.\n\n"), progname);
 	printf(_("Usage:\n"));
 	printf(_("  %s init[db]               [-D DATADIR] [-s] [-o \"OPTIONS\"]\n"), progname);
 	printf(_("  %s start   [-w] [-t SECS] [-D DATADIR] [-s] [-l FILENAME] [-o \"OPTIONS\"]\n"), progname);
 	printf(_("  %s stop    [-W] [-t SECS] [-D DATADIR] [-s] [-m SHUTDOWN-MODE]\n"), progname);
 	printf(_("  %s restart [-w] [-t SECS] [-D DATADIR] [-s] [-m SHUTDOWN-MODE]\n"
 			 "                 [-o \"OPTIONS\"]\n"), progname);
-	printf(_("  %s promote [-D DATADIR] [-s]\n"), progname);
 	printf(_("  %s reload  [-D DATADIR] [-s]\n"), progname);
 	printf(_("  %s status  [-D DATADIR]\n"), progname);
+	printf(_("  %s promote [-D DATADIR] [-s]\n"), progname);
 	printf(_("  %s kill    SIGNALNAME PID\n"), progname);
 #if defined(WIN32) || defined(__CYGWIN__)
 	printf(_("  %s register   [-N SERVICENAME] [-U USERNAME] [-P PASSWORD] [-D DATADIR]\n"
@@ -2066,12 +2070,12 @@ main(int argc, char **argv)
 				ctl_command = STOP_COMMAND;
 			else if (strcmp(argv[optind], "restart") == 0)
 				ctl_command = RESTART_COMMAND;
-			else if (strcmp(argv[optind], "promote") == 0)
-				ctl_command = PROMOTE_COMMAND;
 			else if (strcmp(argv[optind], "reload") == 0)
 				ctl_command = RELOAD_COMMAND;
 			else if (strcmp(argv[optind], "status") == 0)
 				ctl_command = STATUS_COMMAND;
+			else if (strcmp(argv[optind], "promote") == 0)
+				ctl_command = PROMOTE_COMMAND;
 			else if (strcmp(argv[optind], "kill") == 0)
 			{
 				if (argc - optind < 3)
@@ -2174,12 +2178,12 @@ main(int argc, char **argv)
 		case RESTART_COMMAND:
 			do_restart();
 			break;
-		case PROMOTE_COMMAND:
-			do_promote();
-			break;
 		case RELOAD_COMMAND:
 			do_reload();
 			break;
+		case PROMOTE_COMMAND:
+			do_promote();
+			break;
 		case KILL_COMMAND:
 			do_kill(killproc);
 			break;