Note incompatibility with Oracle's version of FOR ... REVERSE, per

Andrew Dunstan.  Minor other improvements in documentation of integer
FOR loops.

diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index 562dfad728ef9ada7bf26ca3111476987ed1ba7e..59ec377ea9de6f7a0b5ca601ea0474eeedc04d47 100644 (file)
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -1,4 +1,4 @@
-
+
 
  
   <application>PL/pgSQL</application> - <acronym>SQL</acronym> Procedural Language
@@ -1757,7 +1757,7 @@ END LOOP;
        
      
 
-     
+      id="plpgsql-integer-for">
       <literal>FOR</> (integer variant)
 
 
@@ -1777,7 +1777,8 @@ END LOOP  label ;
         the lower and upper bound of the range are evaluated once when entering
         the loop. If the BY clause isn't specified the iteration 
         step is 1, otherwise it's the value specified in the BY 
-        clause. If REVERSE is specified then the step value is 
+        clause, which again is evaluated once on loop entry.
+        If REVERSE is specified then the step value is 
         subtracted, rather than added, after each iteration.
        
 
@@ -1785,17 +1786,15 @@ END LOOP  label ;
         Some examples of integer FOR loops:
 
 FOR i IN 1..10 LOOP
-    -- some computations here
-    RAISE NOTICE 'i is %', i;
+    -- i will take on the values 1,2,3,4,5,6,7,8,9,10 within the loop
 END LOOP;
 
 FOR i IN REVERSE 10..1 LOOP
-    -- some computations here
+    -- i will take on the values 10,9,8,7,6,5,4,3,2,1 within the loop
 END LOOP;
 
 FOR i IN REVERSE 10..1 BY 2 LOOP
-    -- some computations here
-    RAISE NOTICE 'i is %', i;
+    -- i will take on the values 10,8,6,4,2 within the loop
 END LOOP;
 
        
@@ -1805,6 +1804,13 @@ END LOOP;
         in the REVERSE case), the loop body is not
         executed at all.  No error is raised.
        
+
+       
+        If a label is attached to the
+        FOR loop then the integer loop variable can be
+        referenced with a qualified name, using that
+        label.
+       
      
    
 
@@ -3654,6 +3660,18 @@ a_output := a_output || $$ if v_$$ || referrer_keys.kind || $$ like '$$
       
      
 
+     
+      
+       Integer FOR loops with REVERSE work
+       differently: PL/SQL counts down from the second
+       number to the first, while PL/pgSQL counts down
+       from the first number to the second, requiring the loop bounds
+       to be swapped when porting.  This incompatibility is unfortunate
+       but is unlikely to be changed. (See 
+       linkend="plpgsql-integer-for">.)
+      
+     
+