Whack some sense into the configuration-file-location patch.

Refactor code into something reasonably understandable, cause
use of the feature to not fail in standalone backends or in
EXEC_BACKEND case, fix sloppy guc.c table entries, make the
documentation minimally usable.

3 files changed, 65 insertions, 27 deletions

diff --git a/doc/src/sgml/ref/postgres-ref.sgml b/doc/src/sgml/ref/postgres-ref.sgml
index cfb16a78686..b0a5f920a9e 100644
--- a/doc/src/sgml/ref/postgres-ref.sgml
+++ b/doc/src/sgml/ref/postgres-ref.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.43 2004/02/03 17:34:02 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.44 2004/10/08 01:36:32 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -357,7 +357,7 @@ PostgreSQL documentation
 
     <listitem>
      <para>
-      Default data direction location
+      Default data directory location
      </para>
     </listitem>
    </varlistentry>
diff --git a/doc/src/sgml/ref/postmaster.sgml b/doc/src/sgml/ref/postmaster.sgml
index d7255dc87f7..518f958e519 100644
--- a/doc/src/sgml/ref/postmaster.sgml
+++ b/doc/src/sgml/ref/postmaster.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.52 2004/09/20 00:04:19 neilc Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.53 2004/10/08 01:36:32 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -67,27 +67,22 @@ PostgreSQL documentation
    One <command>postmaster</command> always manages the data
    from exactly one database cluster.  A database cluster is a
    collection of databases that is stored at a common file system
-   location.  When the <command>postmaster</command> starts it needs 
-   to know the location of the database cluster files (<quote>data 
-   area</quote>).  
+   location (the <quote>data area</quote>).
    More than one <command>postmaster</command> process can run on a system
-   at one time as long as they use different data areas and different
+   at one time, so long as they use different data areas and different
    communication ports (see below).  A data area is created with <xref
    linkend="app-initdb">.
   </para>
 
   <para>
-   The <quote>data area</> is specified by the <option>-D</option> option
+   When the <command>postmaster</command> starts it needs 
+   to know the location of the data area.
+   The location must be specified by the <option>-D</option> option
    or the <envar>PGDATA</envar> environment variable; there is no default.
-   Typically, it points to a directory created by <application>
-   initdb</>.  However, for administrative flexibility, you can
-   point to a directory containing only configuration files:
-   <filename>postgresql.conf</>, <filename>pg_hba.conf</>, and
-   <filename>pg_ident.conf</>. You can then set
-   <filename>postgresql.conf</>'s <varname>pgdata</> variable to point to the
-   data directory. You can also point just to the server configuration file
-   like <filename>postgresql.conf</> and set its variables to point to the
-   other configuration files and the data directory.
+   Typically, <option>-D</option> or <envar>PGDATA</envar> points
+   directly to the data area directory created by <application>initdb</>.
+   Other possible file layouts are discussed in
+   <xref linkend="runtime-config-file-locations">.
   </para>
  </refsect1>
 
@@ -154,8 +149,9 @@ PostgreSQL documentation
       <term><option>-D <replaceable class="parameter">datadir</replaceable></option></term>
       <listitem>
        <para>
-	Specifies the file system location of the data directory.  See
-	discussion above.
+        Specifies the file system location of the data directory or
+        configuration file(s).  See
+        <xref linkend="runtime-config-file-locations"> for details.
        </para>
       </listitem>
      </varlistentry>
@@ -394,7 +390,7 @@ PostgreSQL documentation
 
     <listitem>
      <para>
-      Default data direction location
+      Default data directory location
      </para>
     </listitem>
    </varlistentry>
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index 22e75ae0eb3..f6946a08e18 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.285 2004/09/29 06:27:11 neilc Exp $
+$PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.286 2004/10/08 01:36:31 tgl Exp $
 -->
 
 <Chapter Id="runtime">
@@ -564,17 +564,16 @@ SET ENABLE_SEQSCAN TO OFF;
     any desired selection condition.
    </para>
     
-   <sect2 id="runtime-config-configuration-files">
-    <title>Configuration Files</title>
+   <sect2 id="runtime-config-file-locations">
+    <title>File Locations</title>
 
      <variablelist>
-
      <varlistentry id="guc-pgdata" xreflabel="pgdata">
       <term><varname>pgdata</varname> (<type>string</type>)</term>
       <listitem>
        <para>
-         Specifies the directory to use for data storage (everything except
-         configuration files).
+         Specifies the directory to use for data storage.
+         This option can only be set at server start.
        </para>
       </listitem>
      </varlistentry>
@@ -585,6 +584,8 @@ SET ENABLE_SEQSCAN TO OFF;
        <para>
          Specifies the file name to use for configuration of host-based 
          authentication (HBA).
+         This option can only be set at server start or in the
+         <filename>postgresql.conf</filename> file.
        </para>
       </listitem>
      </varlistentry>
@@ -595,6 +596,8 @@ SET ENABLE_SEQSCAN TO OFF;
        <para>
          Specifies the file name to use for configuration of 
          <application>ident</> authentication.
+         This option can only be set at server start or in the
+         <filename>postgresql.conf</filename> file.
        </para>
       </listitem>
      </varlistentry>
@@ -605,11 +608,50 @@ SET ENABLE_SEQSCAN TO OFF;
        <para>
          Specifies the location of an additional <application>postmaster</>
          process-id (PID) file for use by server administration programs.
+         This option can only be set at server start.
        </para>
       </listitem>
      </varlistentry>
-
      </variablelist>
+
+     <para>
+      In a default installation, none of the above options is set explicitly
+      in the <filename>postgresql.conf</filename> file.  In this case, the
+      data directory is specified by the <option>-D</option> command-line
+      option or the <envar>PGDATA</envar> environment variable; there is no
+      default for it.  The configuration files are all placed within the
+      data directory.
+     </para>
+
+     <para>
+      It is also possible to separate the configuration files from the data
+      directory, which can ease administration.  (In particular it is often
+      easier to ensure that the configuration files are properly backed-up
+      when they are kept separate.)  To do this, the <option>-D</option>
+      command-line option or <envar>PGDATA</envar> environment variable
+      must point to the directory containing the configuration files,
+      and the <varname>pgdata</> option is set in
+      <filename>postgresql.conf</filename> (or on the command line) to show
+      where the data directory is actually located.
+     </para>
+
+     <para>
+      If you wish, you can also make the <option>-D</option>
+      command-line option or <envar>PGDATA</envar> environment variable
+      point directly to the master configuration file (which then need not be
+      named <filename>postgresql.conf</filename>).  The <varname>pgdata</>
+      option must be set to determine the data directory location.
+      The other configuration files will by default be sought
+      in the data directory.
+     </para>
+
+     <para>
+      With any of these approaches, you can specify the locations of the
+      secondary configuration files (<filename>pg_hba.conf</> and
+      <filename>pg_ident.conf</>) by setting <varname>hba_conf</> and/or
+      <varname>ident_conf</> in the master configuration file.  These options
+      override the normal locations and names of the secondary files.
+     </para>
    </sect2>
 
    <sect2 id="runtime-config-connection">