Put options in some sensible order

For the --help output and reference pages of pg_dump, pg_dumpall,
pg_restore, put the options in some consistent, mostly alphabetical,
and consistent order, rather than newest option last or something like
that.

Author: petere

doc/src/sgml/ref/pg_dump.sgml

@@ -558,25 +558,6 @@ PostgreSQL documentation
       </listitem>
      </varlistentry>
 
-     <varlistentry>
-      <term><option>--inserts</option></term>
-      <listitem>
-       <para>
-        Dump data as <command>INSERT</command> commands (rather
-        than <command>COPY</command>).  This will make restoration very slow;
-        it is mainly useful for making dumps that can be loaded into
-        non-<productname>PostgreSQL</productname> databases.
-        However, since this option generates a separate command for each row,
-        an error in reloading a row causes only that row to be lost rather
-        than the entire table contents.
-        Note that
-        the restore might fail altogether if you have rearranged column order.
-        The <option>--column-inserts</option> option is safe against column
-        order changes, though even slower.
-       </para>
-      </listitem>
-     </varlistentry>
-
      <varlistentry>
       <term><option>--column-inserts</option></term>
       <term><option>--attribute-inserts</option></term>
@@ -633,6 +614,25 @@ PostgreSQL documentation
       </listitem>
      </varlistentry>
 
+     <varlistentry>
+      <term><option>--inserts</option></term>
+      <listitem>
+       <para>
+        Dump data as <command>INSERT</command> commands (rather
+        than <command>COPY</command>).  This will make restoration very slow;
+        it is mainly useful for making dumps that can be loaded into
+        non-<productname>PostgreSQL</productname> databases.
+        However, since this option generates a separate command for each row,
+        an error in reloading a row causes only that row to be lost rather
+        than the entire table contents.
+        Note that
+        the restore might fail altogether if you have rearranged column order.
+        The <option>--column-inserts</option> option is safe against column
+        order changes, though even slower.
+       </para>
+      </listitem>
+     </varlistentry>
+
      <varlistentry>
       <term><option>--lock-wait-timeout=<replaceable class="parameter">timeout</replaceable></option></term>
       <listitem>
@@ -650,36 +650,10 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
-      <term><option>--serializable-deferrable</option></term>
+      <term><option>--no-security-labels</option></term>
       <listitem>
        <para>
-        Use a <literal>serializable</literal> transaction for the dump, to
-        ensure that the snapshot used is consistent with later database
-        states; but do this by waiting for a point in the transaction stream
-        at which no anomalies can be present, so that there isn't a risk of
-        the dump failing or causing other transactions to roll back with a
-        <literal>serialization_failure</literal>.  See <xref linkend="mvcc">
-        for more information about transaction isolation and concurrency
-        control.
-       </para>
-
-       <para>
-        This option is not beneficial for a dump which is intended only for
-        disaster recovery.  It could be useful for a dump used to load a
-        copy of the database for reporting or other read-only load sharing
-        while the original database continues to be updated.  Without it the
-        dump may reflect a state which is not consistent with any serial
-        execution of the transactions eventually committed.  For example, if
-        batch processing techniques are used, a batch may show as closed in
-        the dump without all of the items which are in the batch appearing.
-       </para>
-
-       <para>
-        This option will make no difference if there are no read-write
-        transactions active when pg_dump is started.  If read-write
-        transactions are active, the start of the dump may be delayed for an
-        indeterminate length of time.  Once running, performance with or
-        without the switch is the same.
+        Do not dump security labels.
        </para>
       </listitem>
      </varlistentry>
@@ -702,47 +676,73 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
-      <term><option>--no-security-labels</option></term>
+      <term><option>--no-unlogged-table-data</option></term>
       <listitem>
        <para>
-        Do not dump security labels.
+        Do not dump the contents of unlogged tables.  This option has no
+        effect on whether or not the table definitions (schema) are dumped;
+        it only suppresses dumping the table data.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term><option>--use-set-session-authorization</></term>
+      <term><option>--quote-all-identifiers</></term>
       <listitem>
        <para>
-        Output SQL-standard <command>SET SESSION AUTHORIZATION</> commands
-        instead of <command>ALTER OWNER</> commands to determine object
-        ownership.  This makes the dump more standards-compatible, but
-        depending on the history of the objects in the dump, might not restore
-        properly.  Also, a dump using <command>SET SESSION AUTHORIZATION</>
-        will certainly require superuser privileges to restore correctly,
-        whereas <command>ALTER OWNER</> requires lesser privileges.
+        Force quoting of all identifiers.  This may be useful when dumping a
+        database for migration to a future version that may have introduced
+        additional keywords.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term><option>--no-unlogged-table-data</option></term>
+      <term><option>--serializable-deferrable</option></term>
       <listitem>
        <para>
-        Do not dump the contents of unlogged tables.  This option has no
-        effect on whether or not the table definitions (schema) are dumped;
-        it only suppresses dumping the table data.
+        Use a <literal>serializable</literal> transaction for the dump, to
+        ensure that the snapshot used is consistent with later database
+        states; but do this by waiting for a point in the transaction stream
+        at which no anomalies can be present, so that there isn't a risk of
+        the dump failing or causing other transactions to roll back with a
+        <literal>serialization_failure</literal>.  See <xref linkend="mvcc">
+        for more information about transaction isolation and concurrency
+        control.
+       </para>
+
+       <para>
+        This option is not beneficial for a dump which is intended only for
+        disaster recovery.  It could be useful for a dump used to load a
+        copy of the database for reporting or other read-only load sharing
+        while the original database continues to be updated.  Without it the
+        dump may reflect a state which is not consistent with any serial
+        execution of the transactions eventually committed.  For example, if
+        batch processing techniques are used, a batch may show as closed in
+        the dump without all of the items which are in the batch appearing.
+       </para>
+
+       <para>
+        This option will make no difference if there are no read-write
+        transactions active when pg_dump is started.  If read-write
+        transactions are active, the start of the dump may be delayed for an
+        indeterminate length of time.  Once running, performance with or
+        without the switch is the same.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term><option>--quote-all-identifiers</></term>
+      <term><option>--use-set-session-authorization</></term>
       <listitem>
        <para>
-        Force quoting of all identifiers.  This may be useful when dumping a
-        database for migration to a future version that may have introduced
-        additional keywords.
+        Output SQL-standard <command>SET SESSION AUTHORIZATION</> commands
+        instead of <command>ALTER OWNER</> commands to determine object
+        ownership.  This makes the dump more standards-compatible, but
+        depending on the history of the objects in the dump, might not restore
+        properly.  Also, a dump using <command>SET SESSION AUTHORIZATION</>
+        will certainly require superuser privileges to restore correctly,
+        whereas <command>ALTER OWNER</> requires lesser privileges.
        </para>
       </listitem>
      </varlistentry>

doc/src/sgml/ref/pg_dumpall.sgml

@@ -164,54 +164,6 @@ PostgreSQL documentation
       </listitem>
      </varlistentry>
 
-     <varlistentry>
-      <term><option>--lock-wait-timeout=<replaceable class="parameter">timeout</replaceable></option></term>
-      <listitem>
-       <para>
-        Do not wait forever to acquire shared table locks at the beginning of
-        the dump. Instead, fail if unable to lock a table within the specified
-        <replaceable class="parameter">timeout</>. The timeout may be
-        specified in any of the formats accepted by <command>SET
-        statement_timeout</>.  Allowed values vary depending on the server
-        version you are dumping from, but an integer number of milliseconds
-        is accepted by all versions since 7.3.  This option is ignored when
-        dumping from a pre-7.3 server.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
-      <term><option>--no-tablespaces</option></term>
-      <listitem>
-       <para>
-        Do not output commands to create tablespaces nor select tablespaces
-        for objects.
-        With this option, all objects will be created in whichever
-        tablespace is the default during restore.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
-      <term><option>--no-security-labels</option></term>
-      <listitem>
-       <para>
-        Do not dump security labels.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
-      <term><option>--no-unlogged-table-data</option></term>
-      <listitem>
-       <para>
-        Do not dump the contents of unlogged tables.  This option has no
-        effect on whether or not the table definitions (schema) are dumped;
-        it only suppresses dumping the table data.
-       </para>
-      </listitem>
-     </varlistentry>
-
      <varlistentry>
       <term><option>-r</option></term>
       <term><option>--roles-only</option></term>
@@ -301,21 +253,6 @@ PostgreSQL documentation
       </listitem>
      </varlistentry>
 
-     <varlistentry>
-      <term><option>--inserts</option></term>
-      <listitem>
-       <para>
-        Dump data as <command>INSERT</command> commands (rather
-        than <command>COPY</command>).  This will make restoration very slow;
-        it is mainly useful for making dumps that can be loaded into
-        non-<productname>PostgreSQL</productname> databases.  Note that
-        the restore might fail altogether if you have rearranged column order.
-        The <option>--column-inserts</option> option is safer, though even
-        slower.
-       </para>
-      </listitem>
-     </varlistentry>
-
      <varlistentry>
       <term><option>--column-inserts</option></term>
       <term><option>--attribute-inserts</option></term>
@@ -364,14 +301,64 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
-      <term><option>--use-set-session-authorization</></term>
+      <term><option>--inserts</option></term>
       <listitem>
        <para>
-        Output SQL-standard <command>SET SESSION AUTHORIZATION</> commands
-        instead of <command>ALTER OWNER</> commands to determine object
-        ownership.  This makes the dump more standards compatible, but
-        depending on the history of the objects in the dump, might not restore
-        properly.
+        Dump data as <command>INSERT</command> commands (rather
+        than <command>COPY</command>).  This will make restoration very slow;
+        it is mainly useful for making dumps that can be loaded into
+        non-<productname>PostgreSQL</productname> databases.  Note that
+        the restore might fail altogether if you have rearranged column order.
+        The <option>--column-inserts</option> option is safer, though even
+        slower.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>--lock-wait-timeout=<replaceable class="parameter">timeout</replaceable></option></term>
+      <listitem>
+       <para>
+        Do not wait forever to acquire shared table locks at the beginning of
+        the dump. Instead, fail if unable to lock a table within the specified
+        <replaceable class="parameter">timeout</>. The timeout may be
+        specified in any of the formats accepted by <command>SET
+        statement_timeout</>.  Allowed values vary depending on the server
+        version you are dumping from, but an integer number of milliseconds
+        is accepted by all versions since 7.3.  This option is ignored when
+        dumping from a pre-7.3 server.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>--no-security-labels</option></term>
+      <listitem>
+       <para>
+        Do not dump security labels.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>--no-tablespaces</option></term>
+      <listitem>
+       <para>
+        Do not output commands to create tablespaces nor select tablespaces
+        for objects.
+        With this option, all objects will be created in whichever
+        tablespace is the default during restore.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>--no-unlogged-table-data</option></term>
+      <listitem>
+       <para>
+        Do not dump the contents of unlogged tables.  This option has no
+        effect on whether or not the table definitions (schema) are dumped;
+        it only suppresses dumping the table data.
        </para>
       </listitem>
      </varlistentry>
@@ -387,6 +374,19 @@ PostgreSQL documentation
       </listitem>
      </varlistentry>
 
+     <varlistentry>
+      <term><option>--use-set-session-authorization</></term>
+      <listitem>
+       <para>
+        Output SQL-standard <command>SET SESSION AUTHORIZATION</> commands
+        instead of <command>ALTER OWNER</> commands to determine object
+        ownership.  This makes the dump more standards compatible, but
+        depending on the history of the objects in the dump, might not restore
+        properly.
+       </para>
+      </listitem>
+     </varlistentry>
+
      <varlistentry>
        <term><option>-?</></term>
        <term><option>--help</></term>