Add warning about plperl nested named subroutines

Andrew Dunstan

doc/src/sgml/plperl.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/plperl.sgml,v 2.45 2005/08/24 19:16:49 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/plperl.sgml,v 2.46 2005/10/12 14:28:33 momjian Exp $
 -->
 
  <chapter id="plperl">
@@ -53,12 +53,24 @@ CREATE FUNCTION <replaceable>funcname</replaceable> (<replaceable>argument-types
     # PL/Perl function body
 $$ LANGUAGE plperl;
 </programlisting>
-   The body of the function is ordinary Perl code. A PL/Perl function must
+   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