Rewrite window function reference section to more clearly explain

keywords and concepts, based on suggestions by Florian Pflug.

diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml
index 479adc950a80bf661d510dd3baddd460e1b60339..f496fa880049b7eae30a5f8ef0469c8347c18d0b 100644 (file)
--- a/doc/src/sgml/syntax.sgml
+++ b/doc/src/sgml/syntax.sgml
@@ -1742,11 +1742,16 @@ UNBOUNDED FOLLOWING
    
     Here, expression represents any value
     expression that does not itself contain window function calls.
-    The PARTITION BY and ORDER BY lists have
-    essentially the same syntax and semantics as GROUP BY
-    and ORDER BY clauses of the whole query, except that their
+    PARTITION BY behaves like a GROUP
+    BY clause by grouping rows into partitions, except its
     expressions are always just expressions and cannot be output-column
-    names or numbers.
+    names or numbers.   ORDER BY behaves similar to a
+    query-level ORDER BY clause, except it controls the
+    order rows are supplied to the aggregate function within the window
+    frame, and with the same expression restrictions.
+   
+
+   
     window_name is a reference to a named window
     specification defined in the query's WINDOW clause.
     Named window specifications are usually referenced with just
@@ -1760,39 +1765,48 @@ UNBOUNDED FOLLOWING
     page for details.
    
 
+   
+    In RANGE mode, CURRENT ROW starts with
+    the current row's first peer that ORDER BY
+    considers equivalent, and ends with its last equivalent peer.  In 
+    ROWS mode, CURRENT ROW simply starts and ends
+    with the current row.
+   
+
+   
+    UNBOUNDED PRECEDING means that the frame
+    starts with the first row of the partition, and similarly
+    UNBOUNDED FOLLOWING means that the frame ends with the last
+    row of the partition.
+    The value PRECEDING and
+    value FOLLOWING cases are currently only
+    allowed in ROWS mode.  They indicate that the frame starts
+    or ends the specified number of rows before or after the current row.
+    value must be an integer expression not
+    containing any variables, aggregate functions, or window functions.
+    The value must not be null or negative; but it can be zero, which
+    just selects the current row.
+   
+
    
     The frame_clause specifies
     the set of rows constituting the window frame, for those
     window functions that act on the frame instead of the whole partition.
-    If frame_end is omitted it defaults to CURRENT
-    ROW.  Restrictions are that
+    The default framing option is RANGE UNBOUNDED PRECEDING,
+    which is the same as RANGE BETWEEN UNBOUNDED PRECEDING AND
+    CURRENT ROW.  This sets the frame to be all rows from the partition start
+    up through the current row's last peer as specified by ORDER BY,
+    or all partition rows if there is no ORDER BY.
+   
+
+   
+    Restrictions are that
     frame_start cannot be UNBOUNDED FOLLOWING,
     frame_end cannot be UNBOUNDED PRECEDING,
     and the frame_end choice cannot appear earlier in the
     above list than the frame_start choice — for example
     RANGE BETWEEN CURRENT ROW AND value
     PRECEDING is not allowed.
-    The default framing option is RANGE UNBOUNDED PRECEDING,
-    which is the same as RANGE BETWEEN UNBOUNDED PRECEDING AND
-    CURRENT ROW; it sets the frame to be all rows from the partition start
-    up through the current row's last peer in the ORDER BY
-    ordering (which means all rows if there is no ORDER BY).
-    In general, UNBOUNDED PRECEDING means that the frame
-    starts with the first row of the partition, and similarly
-    UNBOUNDED FOLLOWING means that the frame ends with the last
-    row of the partition (regardless of RANGE or ROWS
-    mode).  In ROWS mode, CURRENT ROW
-    means that the frame starts or ends with the current row; but in
-    RANGE mode it means that the frame starts or ends with
-    the current row's first or last peer in the ORDER BY ordering.
-    The value PRECEDING and
-    value FOLLOWING cases are currently only
-    allowed in ROWS mode.  They indicate that the frame starts
-    or ends with the row that many rows before or after the current row.
-    value must be an integer expression not
-    containing any variables, aggregate functions, or window functions.
-    The value must not be null or negative; but it can be zero, which
-    selects the current row itself.