From e0636ca90b819d7ca2e6e6dd35cf84d7032d473b Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Fri, 9 Sep 2022 13:50:42 -0400
Subject: [PATCH] Doc: improve documentation about where the psqlrc files are.

Remove no-longer-accurate claim that Windows lacks home directories.
Clarify the text by more clearly distinguishing which statements
reflect hard-wired choices versus which ones reflect overridable
defaults.  Update the examples of version-specific file names,
and make them track future version changes by using "&majorversion;"
and "&version;".  (BTW, in devel and beta releases this method
correctly says that you can use strings like "16devel" and "15beta4"
as minor version identifiers.)

Back-patch to v15, but not further, with the thought that in older
releases the examples with three-part version numbers still had
some historical relevance.  v15 will be the first major release after
the last 9.x branch went out of support.

Robert Treat and Tom Lane, reviewed by Julien Rouhaud

Discussion: https://postgr.es/m/CAJSLCQ07F-WCYYYOY8+dWhHcVeJ1Pb01cWc-c0Hu=M3EjKT2Eg@mail.gmail.com
---
 doc/src/sgml/ref/psql-ref.sgml | 30 +++++++++++++++++-------------
 1 file changed, 17 insertions(+), 13 deletions(-)

diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index e48ad24700..36a1ba46d5 100644
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -4859,32 +4859,36 @@ PSQL_EDITOR_LINENUMBER_ARG='--line '
      commands.
     </para>
     <para>
-     The system-wide startup file is named <filename>psqlrc</filename> and is
+     The system-wide startup file is named <filename>psqlrc</filename>.
+     By default it is
      sought in the installation's <quote>system configuration</quote> directory,
      which is most reliably identified by running <literal>pg_config
-     --sysconfdir</literal>.  By default this directory will be <filename>../etc/</filename>
+     --sysconfdir</literal>.
+     Typically this directory will be <filename>../etc/</filename>
      relative to the directory containing
-     the <productname>PostgreSQL</productname> executables.  The name of this
-     directory can be set explicitly via the <envar>PGSYSCONFDIR</envar>
-     environment variable.
+     the <productname>PostgreSQL</productname> executables.
+     The directory to look in can be set explicitly via
+     the <envar>PGSYSCONFDIR</envar> environment variable.
     </para>
     <para>
      The user's personal startup file is named <filename>.psqlrc</filename>
-     and is sought in the invoking user's home directory.  On Windows, which
-     lacks such a concept, the personal startup file is named
+     and is sought in the invoking user's home directory.
+     On Windows the personal startup file is instead named
      <filename>%APPDATA%\postgresql\psqlrc.conf</filename>.
-     The location of the user's startup file can be set explicitly via
+     In either case, this default file path can be overridden by setting
      the <envar>PSQLRC</envar> environment variable.
     </para>
     <para>
      Both the system-wide startup file and the user's personal startup file
      can be made <application>psql</application>-version-specific
      by appending a dash and the <productname>PostgreSQL</productname>
-     major or minor release number to the file name,
-     for example <filename>~/.psqlrc-9.2</filename> or
-     <filename>~/.psqlrc-9.2.5</filename>.  The most specific
-     version-matching file will be read in preference to a
-     non-version-specific file.
+     major or minor release identifier to the file name,
+     for example <filename>~/.psqlrc-&majorversion;</filename> or
+     <filename>~/.psqlrc-&version;</filename>.
+     The most specific version-matching file will be read in preference
+     to a non-version-specific file.
+     These version suffixes are added after determining the file path
+     as explained above.
     </para>
    </listitem>
   </varlistentry>