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