Improve DISCARD documentation.

The new DISCARD SEQUENCES option was inadequately described, and hadn't
been mentioned at all in the initial Description paragraph.  Rather than
rectifying the latter the hard way, it seemed better to rewrite the
description as a summary, instead of having it basically duplicate
statements made under Parameters.  Be more consistent about the ordering
of the options, too.

diff --git a/doc/src/sgml/ref/discard.sgml b/doc/src/sgml/ref/discard.sgml
index 5b06a638c5f93f55fb6501dd775aac8a48367a5e..e859bf7bab790c1258c805f3f4abc8cc1e85ab90 100644 (file)
--- a/doc/src/sgml/ref/discard.sgml
+++ b/doc/src/sgml/ref/discard.sgml
@@ -30,16 +30,10 @@ DISCARD { ALL | PLANS | SEQUENCES | TEMPORARY | TEMP }
 
   <para>
    <command>DISCARD</> releases internal resources associated with a
-   database session. These resources are normally released at the end
-   of the session.
-  </para>
-
-  <para>
-   <command>DISCARD TEMP</> drops all temporary tables created in the
-   current session.  <command>DISCARD PLANS</> releases all internally
-   cached query plans.  <command>DISCARD ALL</> resets a session to
-   its original state, discarding temporary resources and resetting
-   session-local configuration changes.
+   database session.  This command is useful for partially or fully
+   resetting the session's state.  There are several subcommands to
+   release different types of resources; the <command>DISCARD ALL</>
+   variant subsumes all the others, and also resets additional state.
   </para>
  </refsect1>
 
@@ -49,28 +43,34 @@ DISCARD { ALL | PLANS | SEQUENCES | TEMPORARY | TEMP }
   <variablelist>
 
    <varlistentry>
-    <term><literal>TEMPORARY</literal> or <literal>TEMP</literal></term>
+    <term><literal>PLANS</literal></term>
     <listitem>
      <para>
-      Drops all temporary tables created in the current session.
+      Releases all cached query plans, forcing re-planning to occur
+      the next time the associated prepared statement is used.
      </para>
     </listitem>
    </varlistentry>
 
    <varlistentry>
-    <term><literal>PLANS</literal></term>
+    <term><literal>SEQUENCES</literal></term>
     <listitem>
      <para>
-      Releases all cached query plans.
+      Discards all cached sequence-related state,
+      including <function>currval()</>/<function>lastval()</>
+      information and any preallocated sequence values that have not
+      yet been returned by <function>nextval()</>.
+      (See <xref linkend="sql-createsequence"> for a description of
+      preallocated sequence values.)
      </para>
     </listitem>
    </varlistentry>
 
    <varlistentry>
-    <term><literal>SEQUENCES</literal></term>
+    <term><literal>TEMPORARY</literal> or <literal>TEMP</literal></term>
     <listitem>
      <para>
-      Discards all cached sequence values.
+      Drops all temporary tables created in the current session.
      </para>
     </listitem>
    </varlistentry>
@@ -91,8 +91,8 @@ CLOSE ALL;
 UNLISTEN *;
 SELECT pg_advisory_unlock_all();
 DISCARD PLANS;
-DISCARD TEMP;
 DISCARD SEQUENCES;
+DISCARD TEMP;
 </programlisting></para>
     </listitem>
    </varlistentry>