From 0969a7aa3240eaa27f6978da6870f9eef706b356 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Thu, 15 Aug 2019 11:14:26 -0400
Subject: [PATCH] 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
---
 doc/src/sgml/config.sgml | 33 +++++++++++++++++++++++----------
 1 file changed, 23 insertions(+), 10 deletions(-)

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 3483ad66cd4..7fbb6f4a5af 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -136,6 +136,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.
     </para>
 
     <para>
@@ -165,22 +167,33 @@ shared_buffers = 128MB
     </para>
 
     <para>
-     In addition to <filename>postgresql.conf</>,
+     In addition to <filename>postgresql.conf</filename>,
      a <productname>PostgreSQL</productname> data directory contains a file
-     <filename>postgresql.auto.conf</><indexterm><primary>postgresql.auto.conf</></>,
-     which has the same format as <filename>postgresql.conf</> but should
-     never be edited manually.  This file holds settings provided through
-     the <xref linkend="SQL-ALTERSYSTEM"> command.  This file is automatically
-     read whenever <filename>postgresql.conf</> is, and its settings take
-     effect in the same way.  Settings in <filename>postgresql.auto.conf</>
-     override those in <filename>postgresql.conf</>.
+     <filename>postgresql.auto.conf</filename><indexterm><primary>postgresql.auto.conf</primary></indexterm>,
+     which has the same format as <filename>postgresql.conf</filename> but
+     is intended to be edited automatically not manually.  This file holds
+     settings provided through the <xref linkend="SQL-ALTERSYSTEM"> command.
+     This file is read whenever <filename>postgresql.conf</filename> is,
+     and its settings take effect in the same way.  Settings
+     in <filename>postgresql.auto.conf</filename> override those
+     in <filename>postgresql.conf</filename>.
+    </para>
+
+    <para>
+     External tools may also
+     modify <filename>postgresql.auto.conf</filename>.  It is not
+     recommended to do this while the server is running, since a
+     concurrent <command>ALTER SYSTEM</command> 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 <command>ALTER SYSTEM</command> will).
     </para>
 
     <para>
      The system view
      <link linkend="view-pg-file-settings"><structname>pg_file_settings</structname></link>
-     can be helpful for pre-testing changes to the configuration file, or for
-     diagnosing problems if a <systemitem>SIGHUP</> signal did not have the
+     can be helpful for pre-testing changes to the configuration files, or for
+     diagnosing problems if a <systemitem>SIGHUP</systemitem> signal did not have the
      desired effects.
     </para>
    </sect2>