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- 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

diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index 186f8c506abdb95a60159cd85f7aab1ed1bcee59..9494f28063add052fd4b91fdf61f9559f7add72b 100644 (file)
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -4892,32 +4892,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>