Marginal tweaks in the documentation for ORDER BY; in particular point

out the common error that ORDER BY x, y DESC does not mean the same as
ORDER BY x DESC, y DESC.

Author: tglsfdc

doc/src/sgml/queries.sgml

@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/queries.sgml,v 1.40 2007/01/09 02:14:10 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/queries.sgml,v 1.41 2007/01/09 16:59:20 tgl Exp $ -->
 
 <chapter id="queries">
  <title>Queries</title>
@@ -1262,6 +1262,13 @@ SELECT a, b FROM table1 ORDER BY a + b, c;
    <literal>DESC</> order, and <literal>NULLS LAST</> otherwise.
   </para>
 
+  <para>
+   Note that the ordering options are considered independently for each
+   sort column.  For example <literal>ORDER BY x, y DESC</> means
+   <literal>ORDER BY x ASC, y DESC</>, which is not the same as
+   <literal>ORDER BY x DESC, y DESC</>.
+  </para>
+
   <para>
    For backwards compatibility with the SQL92 version of the standard,
    a <replaceable>sort_expression</> can instead be the name or number

doc/src/sgml/ref/select.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.95 2007/01/09 02:14:10 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.96 2007/01/09 16:59:20 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -644,13 +644,6 @@ HAVING <replaceable class="parameter">condition</replaceable>
 <synopsis>
 ORDER BY <replaceable class="parameter">expression</replaceable> [ ASC | DESC | USING <replaceable class="parameter">operator</replaceable> ] [ NULLS { FIRST | LAST } ] [, ...]
 </synopsis>
-    <replaceable class="parameter">expression</replaceable> can be the
-    name or ordinal number of an output column
-    (<command>SELECT</command> list item), or it can be an arbitrary
-    expression formed from input-column values.
-   </para>
-
-   <para>
     The <literal>ORDER BY</literal> clause causes the result rows to
     be sorted according to the specified expression(s).  If two rows are
     equal according to the leftmost expression, they are compared
@@ -659,6 +652,13 @@ ORDER BY <replaceable class="parameter">expression</replaceable> [ ASC | DESC |
     an implementation-dependent order.
    </para>
 
+   <para>
+    Each <replaceable class="parameter">expression</replaceable> can be the
+    name or ordinal number of an output column
+    (<command>SELECT</command> list item), or it can be an arbitrary
+    expression formed from input-column values.
+   </para>
+
    <para>
     The ordinal number refers to the ordinal (left-to-right) position
     of the result column. This feature makes it possible to define an
@@ -717,6 +717,12 @@ SELECT name FROM distributors ORDER BY code;
     on whether the operator is a less-than or greater-than operator.
    </para>
 
+   <para>
+    Note that ordering options apply only to the expression they follow;
+    for example <literal>ORDER BY x, y DESC</> does not mean
+    the same thing as <literal>ORDER BY x DESC, y DESC</>.
+   </para>
+
    <para>
     Character-string data is sorted according to the locale-specific
     collation order that was established when the database cluster