From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Thu, 1 Dec 2011 21:39:02 +0000 (-0500)
Subject: Clarify documentation about SQL:2008 variant of LIMIT/OFFSET syntax.
X-Git-Tag: REL9_1_2~1
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=92b9e439e7f0bc54e291e12f5216fb09a72f5b04;p=postgresql

Clarify documentation about SQL:2008 variant of LIMIT/OFFSET syntax.

The point that you need parentheses for non-constant expressions apparently
needs to be brought out a bit more clearly, per bug #6315.
---

diff --git a/doc/src/sgml/ref/select.sgml b/doc/src/sgml/ref/select.sgml
index f890ab2c83..9f53f77804 100644
--- a/doc/src/sgml/ref/select.sgml
+++ b/doc/src/sgml/ref/select.sgml
@@ -1063,7 +1063,8 @@ SELECT name FROM distributors ORDER BY code;
 <synopsis>
 LIMIT { <replaceable class="parameter">count</replaceable> | ALL }
 OFFSET <replaceable class="parameter">start</replaceable>
-</synopsis><replaceable class="parameter">count</replaceable> specifies the
+</synopsis>
+    <replaceable class="parameter">count</replaceable> specifies the
     maximum number of rows to return, while <replaceable
     class="parameter">start</replaceable> specifies the number of rows
     to skip before starting to return rows.  When both are specified,
@@ -1086,17 +1087,19 @@ OFFSET <replaceable class="parameter">start</replaceable>
 OFFSET <replaceable class="parameter">start</replaceable> { ROW | ROWS }
 FETCH { FIRST | NEXT } [ <replaceable class="parameter">count</replaceable> ] { ROW | ROWS } ONLY
 </synopsis>
-    According to the standard, the <literal>OFFSET</literal> clause must come
-    before the <literal>FETCH</literal> clause if both are present; but
-    <productname>PostgreSQL</> is laxer and allows either order.
+    In this syntax, to write anything except a simple integer constant for
+    <replaceable class="parameter">start</> or <replaceable
+    class="parameter">count</replaceable>, you must write parentheses
+    around it.
+    If <replaceable class="parameter">count</> is
+    omitted in a <literal>FETCH</> clause, it defaults to 1.
     <literal>ROW</literal>
     and <literal>ROWS</literal> as well as <literal>FIRST</literal>
     and <literal>NEXT</literal> are noise words that don't influence
-    the effects of these clauses.  In this syntax, when using expressions
-    other than simple constants for <replaceable class="parameter">start</>
-    or <replaceable class="parameter">count</replaceable>, parentheses will be
-    necessary in most cases.  If <replaceable class="parameter">count</> is
-    omitted in <literal>FETCH</>, it defaults to 1.
+    the effects of these clauses.
+    According to the standard, the <literal>OFFSET</literal> clause must come
+    before the <literal>FETCH</literal> clause if both are present; but
+    <productname>PostgreSQL</> is laxer and allows either order.
    </para>
 
    <para>