Improve FILES section of psql reference page.

Primarily, explain where to find the system-wide psqlrc file, per recent
gripe from John Sutton.  Do some general wordsmithing and improve the
markup, too.

Also adjust psqlrc.sample so its comments about file location are somewhat
trustworthy.  (Not sure why we bother with this file when it's empty,
but whatever.)

Back-patch to 9.2 where the startup file naming scheme was last changed.

diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index 574db5c14c6fdfeb18d6b645c6bd1133bcf72c92..5ad84381aba726c7fcd16e3da3581c0ec424edd9 100644 (file)
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -3516,42 +3516,53 @@ PSQL_EDITOR_LINENUMBER_ARG='--line '
  
   Files
 
-  
+ 
+  
+   psqlrc and ~/.psqlrc
    
     
-     Unless it is passed an -X
-     or -c option,
-     psql attempts to
-     read and execute commands from the system-wide
-     psqlrc file and the user's
-     ~/.psqlrc file before starting up.
-     (On Windows, the user's startup file is named
-     %APPDATA%\postgresql\psqlrc.conf.)
-     See PREFIX/share/psqlrc.sample
-     for information on setting up the system-wide file.  It could be used
-     to set up the client or the server to taste (using the \set
-      and SET commands).
+     Unless it is passed an -X or -c option,
+     psql attempts to read and execute commands
+     from the system-wide startup file (psqlrc) and then
+     the user's personal startup file (~/.psqlrc), after
+     connecting to the database but before accepting normal commands.
+     These files can be used to set up the client and/or the server to taste,
+     typically with \set and SET
+     commands.
     
     
-     The location of the user's ~/.psqlrc file can
-     also be set explicitly via the PSQLRC environment
-     setting.
+     The system-wide startup file is named psqlrc and is
+     sought in the installation's system configuration directory,
+     which is most reliably identified by running pg_config
+     --sysconfdir.  By default this directory will be ../etc/
+     relative to the directory containing
+     the PostgreSQL executables.  The name of this
+     directory can be set explicitly via the PGSYSCONFDIR
+     environment variable.
+    
+    
+     The user's personal startup file is named .psqlrc
+     and is sought in the invoking user's home directory.  On Windows, which
+     lacks such a concept, the personal startup file is named
+     %APPDATA%\postgresql\psqlrc.conf.
+     The location of the user's startup file can be set explicitly via
+     the PSQLRC environment variable.
     
-   
-
-   
     
-     Both the system-wide psqlrc file and the user's
-     ~/.psqlrc file can be made psql-version-specific
+     Both the system-wide startup file and the user's personal startup file
+     can be made psql-version-specific
      by appending a dash and the PostgreSQL
-     major or minor psql release number,
+     major or minor release number to the file name,
      for example ~/.psqlrc-9.2 or
      ~/.psqlrc-9.2.5.  The most specific
      version-matching file will be read in preference to a
      non-version-specific file.
     
    
+  
 
+  
+   .psql_history
    
     
      The command-line history is stored in the file
@@ -3559,12 +3570,12 @@ PSQL_EDITOR_LINENUMBER_ARG='--line '
      %APPDATA%\postgresql\psql_history on Windows.
     
     
-     The location of the history file can
-     also be set explicitly via the PSQL_HISTORY environment
-     setting.
+     The location of the history file can be set explicitly via
+     the PSQL_HISTORY environment variable.
     
    
-  
+  
+ 
  
 
 

diff --git a/src/bin/psql/psqlrc.sample b/src/bin/psql/psqlrc.sample
index 6054fabb380e5e2b0bb86206318331e1fd54ebfc..8152cace2b06f6982bd0b2c894bfc2ccfc342294 100644 (file)
--- a/src/bin/psql/psqlrc.sample
+++ b/src/bin/psql/psqlrc.sample
@@ -1,7 +1,8 @@
 --
--- psql configuration file
+-- system-wide psql configuration file
 --
 --  This file is read before the .psqlrc file in the user's home directory.
 --
---  Copy this to your sysconf directory (typically /usr/local/pgsql/etc) and
---  rename it psqlrc.
+--  Copy this to your installation's sysconf directory and rename it psqlrc.
+--  The sysconf directory can be identified via "pg_config --sysconfdir".
+--