Doc: improve documentation about postgresql.auto.conf.

Clarify what external tools can do to this file, and add a bit
of detail about what ALTER SYSTEM itself does.

Discussion: https://postgr.es/m/aed6cc9f-98f3-2693-ac81-52bb0052307e@2ndquadrant.com

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index cdc30fa5e31e9cb72b14cbc10acd7a54303bd74c..e99482d3991e3d4d29a0156764bde68d9e869e3a 100644 (file)
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -153,6 +153,8 @@ shared_buffers = 128MB
      identifiers or numbers must be single-quoted.  To embed a single
      quote in a parameter value, write either two quotes (preferred)
      or backslash-quote.
+     If the file contains multiple entries for the same parameter,
+     all but the last one are ignored.
     
 
     
@@ -185,18 +187,29 @@ shared_buffers = 128MB
      In addition to postgresql.conf,
      a PostgreSQL data directory contains a file
      postgresql.auto.confpostgresql.auto.conf,
-     which has the same format as postgresql.conf but should
-     never be edited manually.  This file holds settings provided through
-     the  command.  This file is automatically
-     read whenever postgresql.conf is, and its settings take
-     effect in the same way.  Settings in postgresql.auto.conf
-     override those in postgresql.conf.
+     which has the same format as postgresql.conf but
+     is intended to be edited automatically not manually.  This file holds
+     settings provided through the  command.
+     This file is read whenever postgresql.conf is,
+     and its settings take effect in the same way.  Settings
+     in postgresql.auto.conf override those
+     in postgresql.conf.
+    
+
+    
+     External tools may also
+     modify postgresql.auto.conf.  It is not
+     recommended to do this while the server is running, since a
+     concurrent ALTER SYSTEM command could overwrite
+     such changes.  Such tools might simply append new settings to the end,
+     or they might choose to remove duplicate settings and/or comments
+     (as ALTER SYSTEM will).
     
 
     
      The system view
      pg_file_settings
-     can be helpful for pre-testing changes to the configuration file, or for
+     can be helpful for pre-testing changes to the configuration files, or for
      diagnosing problems if a SIGHUP signal did not have the
      desired effects.