From 0898d71f66ed884af726556ac9ffc8081dddc757 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Sat, 15 Oct 2011 13:02:37 -0400
Subject: [PATCH] Marginal improvements to documentation of plpgsql's OPEN
 cursor statement.

Rearrange text to improve clarity, and add an example of implicit reference
to a plpgsql variable in a bound cursor's query.  Byproduct of some work
I'd done on the "named cursor parameters" patch before giving up on it.
---
 doc/src/sgml/plpgsql.sgml | 44 +++++++++++++++++++++++++--------------
 1 file changed, 28 insertions(+), 16 deletions(-)

diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index c14c34cd32..19c15ad26f 100644
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -2720,7 +2720,7 @@ END;
 DECLARE
     curs1 refcursor;
     curs2 CURSOR FOR SELECT * FROM tenk1;
-    curs3 CURSOR (key integer) IS SELECT * FROM tenk1 WHERE unique1 = key;
+    curs3 CURSOR (key integer) FOR SELECT * FROM tenk1 WHERE unique1 = key;
 </programlisting>
      All three of these variables have the data type <type>refcursor</>,
      but the first can be used with any query, while the second has
@@ -2836,31 +2836,43 @@ OPEN <replaceable>bound_cursorvar</replaceable> <optional> ( <replaceable>argume
           cursor cannot be open already.  A list of actual argument value
           expressions must appear if and only if the cursor was declared to
           take arguments.  These values will be substituted in the query.
+         </para>
+
+         <para>
           The query plan for a bound cursor is always considered cacheable;
           there is no equivalent of <command>EXECUTE</command> in this case.
-          Notice that <literal>SCROLL</> and
-          <literal>NO SCROLL</> cannot be specified, as the cursor's scrolling
+          Notice that <literal>SCROLL</> and <literal>NO SCROLL</> cannot be
+          specified in <command>OPEN</>, as the cursor's scrolling
           behavior was already determined.
          </para>
 
          <para>
-          Note that because variable substitution is done on the bound
-          cursor's query, there are two ways to pass values into the cursor:
-          either with an explicit argument to <command>OPEN</>, or
-          implicitly by referencing a <application>PL/pgSQL</> variable
-          in the query.  However, only variables declared before the bound
-          cursor was declared will be substituted into it.  In either case
-          the value to be passed is determined at the time of the
-          <command>OPEN</>.
-         </para>
-
-    <para>
-     Examples:
+          Examples (these use the cursor declaration examples above):
 <programlisting>
 OPEN curs2;
 OPEN curs3(42);
 </programlisting>
-       </para>
+         </para>
+
+         <para>
+          Because variable substitution is done on a bound cursor's query,
+          there are really two ways to pass values into the cursor: either
+          with an explicit argument to <command>OPEN</>, or implicitly by
+          referencing a <application>PL/pgSQL</> variable in the query.
+          However, only variables declared before the bound cursor was
+          declared will be substituted into it.  In either case the value to
+          be passed is determined at the time of the <command>OPEN</>.
+          For example, another way to get the same effect as the
+          <literal>curs3</> example above is
+<programlisting>
+DECLARE
+    key integer;
+    curs4 CURSOR FOR SELECT * FROM tenk1 WHERE unique1 = key;
+BEGIN
+    key := 42;
+    OPEN curs4;
+</programlisting>
+         </para>
      </sect3>
    </sect2>