Improve discussion of setting server parameters.

Rewrite description of "include_if_exists" for clarity.  Add subsection
headings to make the structure of the page a little clearer.  A couple
other minor improvements too.

Josh Kupershmidt and Tom Lane

doc/src/sgml/config.sgml

@@ -18,6 +18,9 @@
   <sect1 id="config-setting">
    <title>Setting Parameters</title>
 
+   <sect2 id="config-setting-names-values">
+    <title>Parameter Names and Values</title>
+
     <para>
      All parameter names are case-insensitive. Every parameter takes a
      value of one of five types: Boolean, integer, floating point,
@@ -50,6 +53,10 @@
      from <structname>pg_settings</>.<structfield>enumvals</>.
      Enum parameter values are case-insensitive.
     </para>
+   </sect2>
+
+   <sect2 id="config-setting-configuration-file">
+    <title>Setting Parameters via the Configuration File</title>
 
     <para>
      One way to set these parameters is to edit the file
@@ -66,7 +73,7 @@ shared_buffers = 128MB
 </programlisting>
      One parameter is specified per line. The equal sign between name and
      value is optional. Whitespace is insignificant and blank lines are
-    ignored. Hash marks (<literal>#</literal>) designate the rest of the
+     ignored. Hash marks (<literal>#</literal>) designate the remainder of the
      line as a comment.  Parameter values that are not simple identifiers or
      numbers must be single-quoted.  To embed a single quote in a parameter
      value, write either two quotes (preferred) or backslash-quote.
@@ -80,7 +87,9 @@ shared_buffers = 128MB
      In addition to parameter settings, the <filename>postgresql.conf</>
      file can contain <firstterm>include directives</>, which specify
      another file to read and process as if it were inserted into the
-    configuration file at this point.  Include directives simply look like:
+     configuration file at this point.  This feature allows a configuration
+     file to be divided into physically separate parts.
+     Include directives simply look like:
 <programlisting>
 include 'filename'
 </programlisting>
@@ -94,18 +103,20 @@ include 'filename'
       <primary><literal>include_if_exists</></primary>
       <secondary>in configuration file</secondary>
      </indexterm>
-    Use the same approach as the <literal>include</> directive, continuing
+     There is also an <literal>include_if_exists</> directive, which acts
-    normally if the file does not exist.  A regular <literal>include</>
+     the same as the <literal>include</> directive, except for the behavior
-    will stop with an error if the referenced file is missing, while
+     when the referenced file does not exist or cannot be read.  A regular
-    <literal>include_if_exists</> does not.  A warning about the missing
+     <literal>include</> will consider this an error condition, but
-    file will be logged.
+     <literal>include_if_exists</> merely logs a message and continues
+     processing the referencing configuration file.
     </para>
 
     <para>
      <indexterm>
       <primary>SIGHUP</primary>
      </indexterm>
-    The configuration file is reread whenever the main server process receives a
+     The configuration file is reread whenever the main server process
+     receives a
      <systemitem>SIGHUP</> signal (which is most easily sent by means
      of <literal>pg_ctl reload</>). The main server process
      also propagates this signal to all currently running server
@@ -117,10 +128,15 @@ include 'filename'
      configuration file are likewise ignored (but logged) during
      <systemitem>SIGHUP</> processing.
     </para>
+   </sect2>
+
+   <sect2 id="config-setting-other-methods">
+    <title>Other Ways to Set Parameters</title>
 
     <para>
      A second way to set these configuration parameters is to give them
-    as a command-line option to the <command>postgres</command> command, such as:
+     as a command-line option to the <command>postgres</command> command,
+     such as:
 <programlisting>
 postgres -c log_connections=yes -c log_destination='syslog'
 </programlisting>
@@ -169,10 +185,14 @@ SET ENABLE_SEQSCAN TO OFF;
      values for the parameter. Some parameters cannot be changed via
      <command>SET</command>: for example, if they control behavior that
      cannot be changed without restarting the entire
-    <productname>PostgreSQL</productname> server.  Also,
+     <productname>PostgreSQL</productname> server.  Also, some parameters
-    some <command>SET</command> or <command>ALTER</> parameter modifications
+     require superuser permission to change via <command>SET</command> or
-    require superuser permission.
+     <command>ALTER</>.
     </para>
+   </sect2>
+
+   <sect2 id="config-setting-examining">
+    <title>Examining Parameter Settings</title>
 
     <para>
      The <xref linkend="SQL-SHOW">
@@ -188,8 +208,10 @@ SET ENABLE_SEQSCAN TO OFF;
      and <command>SET</>, but can be more convenient
      to use because it can be joined with other tables, or selected from using
      any desired selection condition. It also contains more information about
-    what values are allowed for the parameters.
+     each parameter than is available from <command>SHOW</>.
     </para>
+
+   </sect2>
   </sect1>
 
    <sect1 id="runtime-config-file-locations">