v3-0001-Clarify-error-message-about-specifying-config-fil.patch

From 1d55400adba93381d8a08249c95e4e16fb9a5945 Mon Sep 17 00:00:00 2001
From: "David G. Johnston" <david.g.johnston@gmail.com>
Date: Fri, 2 Feb 2024 14:16:24 -0700
Subject: [PATCH v3] Clarify error message about specifying --config-file

When running without any arguments 'postgres' suggests to specify either
--config-file or -D option. This is somewhat confusing since --config-file
is a GUC and thus not directly described in the --help message.

This patch reduces the amount of confusion. Besides affecting the error
message the patch clarifies corresponding articles in the documentation.

David Johnston, Aleksander Alekseev. Reviewed by Nathan Bossart and
Peter Eisentraut. Reported by Alexey Palazhchenko.

Discussion: https://postgr.es/m/CAJ7c6TMkuLiLfrA%2BEFCPYfhXoMKRxxssB5c86%2Bibxfaz6%2B%3DSdg%40mail.gmail.com
---
 doc/src/sgml/config.sgml           | 11 ++++++-----
 doc/src/sgml/libpq.sgml            |  7 ++++---
 doc/src/sgml/ref/postgres-ref.sgml |  8 +++++---
 src/backend/main/main.c            |  4 ++--
 src/backend/utils/misc/guc.c       |  2 +-
 5 files changed, 18 insertions(+), 14 deletions(-)

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index e93208b2e6..3777cfa52a 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -334,9 +334,10 @@ UPDATE pg_settings SET setting = reset_val WHERE name = 'configuration_parameter
       <para>
        During server startup, parameter settings can be
        passed to the <command>postgres</command> command via the
-       <option>-c</option> command-line parameter.  For example,
+       <option>-c name=value</option> command-line parameter, or its equivalent
+       <option>--name=value</option> variation.  For example,
 <programlisting>
-postgres -c log_connections=yes -c log_destination='syslog'
+postgres -c log_connections=yes --log-destination='syslog'
 </programlisting>
        Settings provided in this way override those set via
        <filename>postgresql.conf</filename> or <command>ALTER SYSTEM</command>,
@@ -353,10 +354,10 @@ postgres -c log_connections=yes -c log_destination='syslog'
       of the session, but do not affect other sessions.
       For historical reasons, the format of <envar>PGOPTIONS</envar> is
       similar to that used when launching the <command>postgres</command>
-      command; specifically, the <option>-c</option> flag must be specified.
-      For example,
+      command; specifically, the <option>-c</option>, or prepended
+      <literal>--</literal>, before the name must be specified. For example,
 <programlisting>
-env PGOPTIONS="-c geqo=off -c statement_timeout=5min" psql
+env PGOPTIONS="-c geqo=off --statement-timeout=5min" psql
 </programlisting>
      </para>
 
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 1d32c226d8..a445e4f280 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1421,9 +1421,10 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
       <listitem>
        <para>
         Specifies command-line options to send to the server at connection
-        start.  For example, setting this to <literal>-c geqo=off</literal> sets the
-        session's value of the <varname>geqo</varname> parameter to
-        <literal>off</literal>.  Spaces within this string are considered to
+        start.  For example, setting this to <literal>-c geqo=off</literal>
+        or <literal>--geoq=off</literal> sets the session's value of the
+        <varname>geqo</varname> parameter to <literal>off</literal>.
+        Spaces within this string are considered to
         separate command-line arguments, unless escaped with a backslash
         (<literal>\</literal>); write <literal>\\</literal> to represent a literal
         backslash.  For a detailed discussion of the available
diff --git a/doc/src/sgml/ref/postgres-ref.sgml b/doc/src/sgml/ref/postgres-ref.sgml
index b13a16a117..cbf06d86cb 100644
--- a/doc/src/sgml/ref/postgres-ref.sgml
+++ b/doc/src/sgml/ref/postgres-ref.sgml
@@ -123,7 +123,8 @@ PostgreSQL documentation
         described in <xref linkend="runtime-config"/>. Most of the
         other command line options are in fact short forms of such a
         parameter assignment.  <option>-c</option> can appear multiple times
-        to set multiple parameters.
+        to set multiple parameters.  See the <option>--name</option>
+        option below for an alternate syntax.
        </para>
       </listitem>
      </varlistentry>
@@ -342,8 +343,9 @@ PostgreSQL documentation
       <term><option>--<replaceable>name</replaceable>=<replaceable>value</replaceable></option></term>
       <listitem>
        <para>
-        Sets a named run-time parameter; a shorter form of
-        <option>-c</option>.
+        Sets the named run-time parameter; a shorter form of
+        <option>-c</option>.  See <xref linkend="runtime-config"/>
+        for a listing of parameters.
        </para>
       </listitem>
      </varlistentry>
diff --git a/src/backend/main/main.c b/src/backend/main/main.c
index bfd0c5ed65..22ffcb1516 100644
--- a/src/backend/main/main.c
+++ b/src/backend/main/main.c
@@ -323,7 +323,7 @@ help(const char *progname)
 	printf(_("Usage:\n  %s [OPTION]...\n\n"), progname);
 	printf(_("Options:\n"));
 	printf(_("  -B NBUFFERS        number of shared buffers\n"));
-	printf(_("  -c NAME=VALUE      set run-time parameter\n"));
+	printf(_("  -c NAME=VALUE      set run-time parameter (see also --NAME)\n"));
 	printf(_("  -C NAME            print value of run-time parameter, then exit\n"));
 	printf(_("  -d 1-5             debugging level\n"));
 	printf(_("  -D DATADIR         database directory\n"));
@@ -340,7 +340,7 @@ help(const char *progname)
 	printf(_("  -s                 show statistics after each query\n"));
 	printf(_("  -S WORK-MEM        set amount of memory for sorts (in kB)\n"));
 	printf(_("  -V, --version      output version information, then exit\n"));
-	printf(_("  --NAME=VALUE       set run-time parameter\n"));
+	printf(_("  --NAME=VALUE       set run-time parameter, a shorter form of -c\n"));
 	printf(_("  --describe-config  describe configuration parameters, then exit\n"));
 	printf(_("  -?, --help         show this help, then exit\n"));
 
diff --git a/src/backend/utils/misc/guc.c b/src/backend/utils/misc/guc.c
index 3fb6803998..e5ae0784d2 100644
--- a/src/backend/utils/misc/guc.c
+++ b/src/backend/utils/misc/guc.c
@@ -1828,7 +1828,7 @@ SelectConfigFiles(const char *userDoption, const char *progname)
 	else
 	{
 		write_stderr("%s does not know where to find the server configuration file.\n"
-					 "You must specify the --config-file or -D invocation "
+					 "You must specify the --config-file (or equivalent -c) or -D invocation "
 					 "option or set the PGDATA environment variable.\n",
 					 progname);
 		return false;
-- 
2.45.0