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.

diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index c14c34cd322488bc326b3e703d8060f9f3371599..19c15ad26fc3d204b52b007babbcfdbaadb075c7 100644 (file)
--- 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;
 
      All three of these variables have the data type refcursor,
      but the first can be used with any query, while the second has
@@ -2836,31 +2836,43 @@ OPEN bound_cursorvar  ( 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.
+         
+
+         
           The query plan for a bound cursor is always considered cacheable;
           there is no equivalent of EXECUTE in this case.
-          Notice that SCROLL and
-          NO SCROLL cannot be specified, as the cursor's scrolling
+          Notice that SCROLL and NO SCROLL cannot be
+          specified in OPEN, as the cursor's scrolling
           behavior was already determined.
          
 
          
-          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 OPEN, or
-          implicitly by referencing a 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
-          OPEN.
-         
-
-    
-     Examples:
+          Examples (these use the cursor declaration examples above):
 
 OPEN curs2;
 OPEN curs3(42);
 
-       
+         
+
+         
+          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 OPEN, or implicitly by
+          referencing a 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 OPEN.
+          For example, another way to get the same effect as the
+          curs3 example above is
+
+DECLARE
+    key integer;
+    curs4 CURSOR FOR SELECT * FROM tenk1 WHERE unique1 = key;
+BEGIN
+    key := 42;
+    OPEN curs4;
+
+