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

From adc6c807d2bc0d73271b47e4d1908e5c069e5b24 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] v4 configs review

---
 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 61038472c5..1eb58c0793 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -333,9 +333,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>,
@@ -352,10 +353,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 d0d5aefadc..89f7aa590d 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1374,9 +1374,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 51ffb8e773..f1b88faa5c 100644
--- a/src/backend/main/main.c
+++ b/src/backend/main/main.c
@@ -324,7 +324,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"));
@@ -341,7 +341,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 8f65ef3d89..297eb1af4f 100644
--- a/src/backend/utils/misc/guc.c
+++ b/src/backend/utils/misc/guc.c
@@ -1822,7 +1822,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.34.1