Add new psql help topics, accessible to both --help and \?.

Add --help=<topic> for the commandline, and \? <topic> as a backslash
command, to show more help than the invocations without parameters
do. "commands", "variables" and "options" currently exist as help
topics describing, respectively, backslash commands, psql variables,
and commandline switches. Without parameters the help commands show
their previous topic.

Some further wordsmithing or extending of the added help content might
be needed; but there seems little benefit delaying the overall feature
further.

Author: Pavel Stehule, editorialized by many

Reviewed-By: Andres Freund, Petr Jelinek, Fujii Masao, MauMau, Abhijit
    Menon-Sen and Erik Rijkers.

Discussion: CAFj8pRDVGuC-nXBfe2CK8vpyzd2Dsr9GVpbrATAnZO=2YQ0s2Q@mail.gmail.com,
    CAFj8pRA54AbTv2RXDTRxiAd8hy8wxmoVLqhJDRCwEnhdd7OUkw@mail.gmail.com

doc/src/sgml/ref/psql-ref.sgml

@@ -560,11 +560,17 @@ EOF
 
     <varlistentry>
       <term><option>-?</></term>
-      <term><option>--help</></term>
+      <term><option>--help[=<replaceable class="parameter">topic</>]</option></term>
       <listitem>
       <para>
-      Show help about <application>psql</application> command line
-      arguments, and exit.
+      Show help about <application>psql</application> and exit. The optional
+      <replaceable class="parameter">topic</> parameter (defaulting
+      to <literal>options</literal>) selects which part of psql is
+      explained: <literal>commands</> describes <application>psql</>'s
+      backslash commands; <literal>options</> describes the commandline
+      switches that can be passed to <application>psql</>;
+      and <literal>variables</> shows help about about psql configuration
+      variables.
       </para>
       </listitem>
     </varlistentry>
@@ -2574,10 +2580,17 @@ testdb=&gt; <userinput>\setenv LESS -imx4F</userinput>
 
 
       <varlistentry>
-        <term><literal>\?</literal></term>
+        <term><literal>\? [ <replaceable class="parameter">topic</> ]</literal></term>
         <listitem>
         <para>
-        Shows help information about the backslash commands.
+        Shows help information. The optional
+        <replaceable class="parameter">topic</> parameter
+        (defaulting to <literal>commands</>) selects which part of psql is
+        explained: <literal>commands</> describes <application>psql</>'s
+        backslash commands; <literal>options</> describes the commandline
+        switches that can be passed to <application>psql</>;
+        and <literal>variables</> shows help about about psql configuration
+        variables.
         </para>
         </listitem>
       </varlistentry>

src/bin/psql/command.c

@@ -1491,7 +1491,19 @@ exec_command(const char *cmd,
 
 	/* \? -- slash command help */
 	else if (strcmp(cmd, "?") == 0)
+	{
+		char	   *opt0 = psql_scan_slash_option(scan_state,
+													OT_NORMAL, NULL, false);
+
+		if (!opt0 || strcmp(opt0, "commands") == 0)
 			slashUsage(pset.popt.topt.pager);
+		else if (strcmp(opt0, "options") == 0)
+			usage(pset.popt.topt.pager);
+		else if (strcmp(opt0, "variables") == 0)
+			helpVariables(pset.popt.topt.pager);
+		else
+			slashUsage(pset.popt.topt.pager);
+	}
 
 #if 0
 

src/bin/psql/help.h

@@ -8,10 +8,12 @@
 #ifndef HELP_H
 #define HELP_H
 
-void		usage(void);
+void		usage(unsigned short int pager);
 
 void		slashUsage(unsigned short int pager);
 
+void		helpVariables(unsigned short int pager);
+
 void		helpSQL(const char *topic, unsigned short int pager);
 
 void		print_copyright(void);

src/bin/psql/startup.c

@@ -77,6 +77,8 @@ static void process_psqlrc_file(char *filename);
 static void showVersion(void);
 static void EstablishVariableSpace(void);
 
+#define NOPAGER		0
+
 /*
  *
  * main
@@ -95,9 +97,9 @@ main(int argc, char *argv[])
 
 	if (argc > 1)
 	{
-		if (strcmp(argv[1], "--help") == 0 || strcmp(argv[1], "-?") == 0)
+		if ((strcmp(argv[1], "-?") == 0) || (argc == 2 && (strcmp(argv[1], "--help") == 0)))
 		{
-			usage();
+			usage(NOPAGER);
 			exit(EXIT_SUCCESS);
 		}
 		if (strcmp(argv[1], "--version") == 0 || strcmp(argv[1], "-V") == 0)
@@ -383,7 +385,7 @@ parse_psql_options(int argc, char *argv[], struct adhoc_opts * options)
 		{"password", no_argument, NULL, 'W'},
 		{"expanded", no_argument, NULL, 'x'},
 		{"no-psqlrc", no_argument, NULL, 'X'},
-		{"help", no_argument, NULL, '?'},
+		{"help", optional_argument, NULL, 1},
 		{NULL, 0, NULL, 0}
 	};
 
@@ -557,20 +559,31 @@ parse_psql_options(int argc, char *argv[], struct adhoc_opts * options)
 				break;
 			case '?':
 				/* Actual help option given */
-				if (strcmp(argv[optind - 1], "--help") == 0 || strcmp(argv[optind - 1], "-?") == 0)
+				if (strcmp(argv[optind - 1], "-?") == 0)
 				{
-					usage();
+					usage(NOPAGER);
 					exit(EXIT_SUCCESS);
 				}
 				/* unknown option reported by getopt */
 				else
+					goto unknown_option;
+				break;
+			case 1:
 				{
-					fprintf(stderr, _("Try \"%s --help\" for more information.\n"),
-							pset.progname);
-					exit(EXIT_FAILURE);
+					if (!optarg || strcmp(optarg, "options") == 0)
+						usage(NOPAGER);
+					else if (optarg && strcmp(optarg, "commands") == 0)
+						slashUsage(NOPAGER);
+					else if (optarg && strcmp(optarg, "variables") == 0)
+						helpVariables(NOPAGER);
+					else
+						goto unknown_option;
+
+					exit(EXIT_SUCCESS);
 				}
 				break;
 			default:
+			unknown_option:
 				fprintf(stderr, _("Try \"%s --help\" for more information.\n"),
 						pset.progname);
 				exit(EXIT_FAILURE);

src/bin/psql/tab-complete.c

@@ -3543,6 +3543,13 @@ psql_completion(const char *text, int start, int end)
 
 /* Backslash commands */
 /* TODO:  \dc \dd \dl */
+	else if (strcmp(prev_wd, "\\?") == 0)
+	{
+		static const char *const my_list[] =
+		{"commands", "options", "variables", NULL};
+
+		COMPLETE_WITH_LIST_CS(my_list);
+	}
 	else if (strcmp(prev_wd, "\\connect") == 0 || strcmp(prev_wd, "\\c") == 0)
 		COMPLETE_WITH_QUERY(Query_for_list_of_databases);