suggested warning about perl nested named subroutines

I propose to add the following to the plperl docs, following recent
problems.

comments?

cheers

andrew


Index: plperl.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/plperl.sgml,v
retrieving revision 2.45
diff -c -r2.45 plperl.sgml
*** plperl.sgml 24 Aug 2005 19:16:49 -0000      2.45
--- plperl.sgml 12 Oct 2005 00:36:33 -0000
***************
*** 53,64 ****
      # PL/Perl function body
  $$ LANGUAGE plperl;
  </programlisting>
!    The body of the function is ordinary Perl code. A PL/Perl function must
     always return a scalar value.  You can return more complex structures
     (arrays, records, and sets) by returning a reference, as discussed
below.
     Never return a list.
    </para>

     <para>
      The syntax of the <command>CREATE FUNCTION</command> command requires
      the function body to be written as a string constant.  It is usually
--- 53,76 ----
      # PL/Perl function body
  $$ LANGUAGE plperl;
  </programlisting>
!    The body of the function is ordinary Perl code. In fact, the PL/Perl
!    glue code wraps it inside a Perl subroutine. A PL/Perl function must
     always return a scalar value.  You can return more complex structures
     (arrays, records, and sets) by returning a reference, as discussed
below.
     Never return a list.
    </para>

+    <note>
+       <para>
+        The use of named nested subroutines is dangerous in Perl,
especially if
+        they refer to lexical variables in the enclosing scope. Because
a PL/Perl
+        function is wrapped in a subroutine, any named subroutine you
create will
+        be nested. In general, it is far safer to create anonymous
subroutines
+        which you call via a coderef. See the <literal>perldiag</literal>
+        man page for more details.
+       </para>
+    </note>
+
     <para>
      The syntax of the <command>CREATE FUNCTION</command> command requires
      the function body to be written as a string constant.  It is usually