Improve documentation around parameter-setting and ALTER SYSTEM.

The ALTER SYSTEM ref page hadn't been held to a very high standard, nor
was the feature well integrated into section 18.1 (parameter setting).
Also, though commit 4c4654afe had improved the structure of 18.1, it also
introduced a lot of poor wording, imprecision, and outright falsehoods.
Try to clean that up.

doc/src/sgml/ref/alter_system.sgml

@@ -32,23 +32,30 @@ ALTER SYSTEM RESET ALL
   <title>Description</title>
 
   <para>
-   <command>ALTER SYSTEM</command> writes the configuration parameter
-   values to the <filename>postgresql.auto.conf</filename> file.
-   Setting the parameter to <literal>DEFAULT</literal>, or using the
-   <command>RESET</command> variant, removes the configuration entry from
+   <command>ALTER SYSTEM</command> is used for changing server configuration
+   parameters across the entire database cluster.  It can be more convenient
+   than the traditional method of manually editing
+   the <filename>postgresql.conf</filename> file.
+   <command>ALTER SYSTEM</command> writes the given parameter setting to
+   the <filename>postgresql.auto.conf</filename> file, which is read in
+   addition to <filename>postgresql.conf</filename>.
+   Setting a parameter to <literal>DEFAULT</literal>, or using the
+   <command>RESET</command> variant, removes that configuration entry from the
    <filename>postgresql.auto.conf</filename> file. Use <literal>RESET
-   ALL</literal> to clear all configuration entries.  The values will
-   be effective after reload of server configuration (SIGHUP) or in next
-   server start based on the type of configuration parameter modified.
+   ALL</literal> to remove all such configuration entries.
   </para>
 
   <para>
-   This command is not allowed inside transaction block or function.
+   Values set with <command>ALTER SYSTEM</command> will be effective after
+   the next server configuration reload (<systemitem>SIGHUP</>
+   or <literal>pg_ctl reload</>), or after the next server restart in the
+   case of parameters that can only be changed at server start.
   </para>
 
   <para>
-   See <xref linkend="config-setting"> for other ways to set the parameters and
-   how they become effective.
+   Only superusers can use <command>ALTER SYSTEM</command>.  Also, since
+   this command acts directly on the file system and cannot be rolled back,
+   it is not allowed inside a transaction block or function.
   </para>
  </refsect1>
 
@@ -60,7 +67,7 @@ ALTER SYSTEM RESET ALL
     <term><replaceable class="parameter">configuration_parameter</replaceable></term>
     <listitem>
      <para>
-      Name of a settable run-time parameter.  Available parameters are
+      Name of a settable configuration parameter.  Available parameters are
       documented in <xref linkend="runtime-config">.
      </para>
     </listitem>
@@ -70,11 +77,11 @@ ALTER SYSTEM RESET ALL
     <term><replaceable class="parameter">value</replaceable></term>
     <listitem>
      <para>
-      New value of parameter.  Values can be specified as string
+      New value of the parameter.  Values can be specified as string
       constants, identifiers, numbers, or comma-separated lists of
       these, as appropriate for the particular parameter.
-      <literal>DEFAULT</literal> can be written to specify to remove the
-      parameter and its value from <filename>postgresql.auto.conf</filename>
+      <literal>DEFAULT</literal> can be written to specify removing the
+      parameter and its value from <filename>postgresql.auto.conf</filename>.
      </para>
     </listitem>
    </varlistentry>
@@ -85,12 +92,16 @@ ALTER SYSTEM RESET ALL
   <title>Notes</title>
 
   <para>
-    This command can't be used to set <xref linkend="guc-data-directory">
-    and any parameters (e.g., <link linkend="runtime-config-preset">preset options</>)
-    that are not allowed in <filename>postgresql.conf</>.
+   This command can't be used to set <xref linkend="guc-data-directory">,
+   nor parameters that are not allowed in <filename>postgresql.conf</>
+   (e.g., <link linkend="runtime-config-preset">preset options</>).
+  </para>
+
+  <para>
+   See <xref linkend="config-setting"> for other ways to set the parameters.
   </para>
  </refsect1>
-  
+
  <refsect1>
   <title>Examples</title>
 
@@ -102,10 +113,12 @@ ALTER SYSTEM SET wal_level = hot_standby;
   </para>
 
   <para>
-   Set the <literal>authentication_timeout</>:
+   Undo that, restoring whatever setting was effective
+   in <filename>postgresql.conf</>:
 <programlisting>
-ALTER SYSTEM SET authentication_timeout = 10;
-</programlisting></para>
+ALTER SYSTEM RESET wal_level;
+</programlisting>
+  </para>
  </refsect1>
 
  <refsect1>