Backpatch documentation additions for PL language choice and

regex_replace() to 8.1.X.

doc/src/sgml/func.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.291.2.5 2005/12/21 23:23:09 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.291.2.6 2006/05/30 12:32:37 momjian Exp $
 PostgreSQL documentation
 -->
 
@@ -1107,7 +1107,9 @@ PostgreSQL documentation
        <entry><literal><function>substring</function>(<parameter>string</parameter> from <replaceable>pattern</replaceable>)</literal></entry>
        <entry><type>text</type></entry>
        <entry>
-        Extract substring matching POSIX regular expression
+        Extract substring matching POSIX regular expression. See
+        <xref linkend="functions-matching"> for more information on pattern
+        matching.
        </entry>
        <entry><literal>substring('Thomas' from '...$')</literal></entry>
        <entry><literal>mas</literal></entry>
@@ -1117,8 +1119,9 @@ PostgreSQL documentation
        <entry><literal><function>substring</function>(<parameter>string</parameter> from <replaceable>pattern</replaceable> for <replaceable>escape</replaceable>)</literal></entry>
        <entry><type>text</type></entry>
        <entry>
-        Extract substring matching <acronym>SQL</acronym> regular
+        Extract substring matching <acronym>SQL</acronym> regular expression.
-        expression
+        See <xref linkend="functions-matching"> for more information on
+        pattern matching.
        </entry>
        <entry><literal>substring('Thomas' from '%#"o_a#"_' for '#')</literal></entry>
        <entry><literal>oma</literal></entry>
@@ -1416,6 +1419,18 @@ PostgreSQL documentation
        <entry><literal>'O''Reilly'</literal></entry>
       </row>
 
+      <row>
+       <entry><literal><function>regexp_replace</function>(<parameter>string</parameter> <type>text</type>, <parameter>pattern</parameter> <type>text</type>, <parameter>replacement</parameter> <type>text</type> [,<parameter>flags</parameter> <type>text</type>])</literal></entry>
+       <entry><type>text</type></entry>
+       <entry>
+        Replace substring matching POSIX regular expression. See
+        <xref linkend="functions-matching"> for more information on pattern
+        matching.
+       </entry>
+       <entry><literal>regexp_replace('Thomas', '.[mN]a.', 'M')</literal></entry>
+       <entry><literal>ThM</literal></entry>
+      </row>
+
       <row>
        <entry><literal><function>repeat</function>(<parameter>string</parameter> <type>text</type>, <parameter>number</parameter> <type>int</type>)</literal></entry>
        <entry><type>text</type></entry>

doc/src/sgml/plperl.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/plperl.sgml,v 2.49 2005/11/04 23:14:00 petere Exp $
+$PostgreSQL: pgsql/doc/src/sgml/plperl.sgml,v 2.49.2.1 2006/05/30 12:32:37 momjian Exp $
 -->
 
  <chapter id="plperl">
@@ -19,6 +19,12 @@ $PostgreSQL: pgsql/doc/src/sgml/plperl.sgml,v 2.49 2005/11/04 23:14:00 petere Ex
    <ulink url="http://www.perl.com">Perl programming language</ulink>.
   </para>
 
+  <para> The usual advantage to using PL/Perl is that this allows use,
+   within stored functions, of the manyfold <quote>string
+    munging</quote> operators and functions available for Perl.  Parsing
+   complex strings may be be easier using Perl than it is with the
+   string functions and control structures provided in PL/pgsql.</para>
+  
   <para>
    To install PL/Perl in a particular database, use
    <literal>createlang plperl <replaceable>dbname</></literal>.

doc/src/sgml/plpgsql.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/plpgsql.sgml,v 1.80.2.4 2006/02/05 02:48:20 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/plpgsql.sgml,v 1.80.2.5 2006/05/30 12:32:37 momjian Exp $
 -->
 
 <chapter id="plpgsql"> 
@@ -157,21 +157,36 @@ $$ LANGUAGE plpgsql;
 
     <para>
      That means that your client application must send each query to
-     the database server, wait for it to be processed, receive the
+     the database server, wait for it to be processed, receive and
-     results, do some computation, then send other queries to the
+     process the results, do some computation, then send further
-     server. All this incurs interprocess communication and may also
+     queries to the server.  All this incurs interprocess
-     incur network overhead if your client is on a different machine
+     communication and will also incur network overhead if your client
-     than the database server.
+     is on a different machine than the database server.
     </para>
 
     <para>
-     With <application>PL/pgSQL</application> you can group a block of computation and a
+     With <application>PL/pgSQL</application> you can group a block of
-     series of queries <emphasis>inside</emphasis> the
+     computation and a series of queries <emphasis>inside</emphasis>
-     database server, thus having the power of a procedural
+     the database server, thus having the power of a procedural
-     language and the ease of use of SQL, but saving lots of
+     language and the ease of use of SQL, but with considerable
-     time because you don't have the whole client/server
+     savings because you don't have the whole client/server
-     communication overhead. This can make for a
+     communication overhead.
-     considerable performance increase.
+    </para>
+    <itemizedlist>
+
+     <listitem><para> Elimination of additional round trips between
+     client and server </para></listitem>
+
+     <listitem><para> Intermediate results that the client does not
+     need do not need to be marshalled or transferred between server
+     and client </para></listitem>
+
+     <listitem><para> There is no need for additional rounds of query
+     parsing </para></listitem>
+
+    </itemizedlist>
+    <para> This can allow for a considerable performance increase as
+    compared to an application that does not use stored functions.
     </para>
 
     <para>

doc/src/sgml/pltcl.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/pltcl.sgml,v 2.38 2005/05/20 01:52:25 neilc Exp $
+$PostgreSQL: pgsql/doc/src/sgml/pltcl.sgml,v 2.38.2.1 2006/05/30 12:32:37 momjian Exp $
 -->
 
  <chapter id="pltcl">
@@ -27,22 +27,27 @@ $PostgreSQL: pgsql/doc/src/sgml/pltcl.sgml,v 2.38 2005/05/20 01:52:25 neilc Exp
    <title>Overview</title>
 
    <para>
-    PL/Tcl offers most of the capabilities a function
+    PL/Tcl offers most of the capabilities a function writer has in
-    writer has in the C language, except for some restrictions.
+    the C language, with a few restrictions, and with the addition of
+    the powerful string processing libraries that are available for
+    Tcl.
    </para>
    <para>
-    The good restriction is that everything is executed in a safe
+    One compelling <emphasis>good</emphasis> restriction is that
-    Tcl interpreter. In addition to the limited command set of safe Tcl, only
+    everything is executed from within the safety of the context of a
-    a few commands are available to access the database via SPI and to raise
+    Tcl interpreter.  In addition to the limited command set of safe
-    messages via <function>elog()</>. There is no way to access internals of the
+    Tcl, only a few commands are available to access the database via
-    database server or to gain OS-level access under the permissions of the
+    SPI and to raise messages via <function>elog()</>.  PL/Tcl
-    <productname>PostgreSQL</productname> server process, as a C function can do.
+    provides no way to access internals of the database server or to
-    Thus, any unprivileged database user may be
+    gain OS-level access under the permissions of the
-    permitted to use this language.
+    <productname>PostgreSQL</productname> server process, as a C
+    function can do.  Thus, unprivileged database users may be trusted
+    to use this language; it does not give them unlimited authority.
    </para>
    <para>
-    The other, implementation restriction is that Tcl functions cannot
+    The other notable implementation restriction is that Tcl functions
-    be used to create input/output functions for new data types.
+    may not be used to create input/output functions for new data
+    types.
    </para>
    <para>
     Sometimes it is desirable to write Tcl functions that are not restricted
@@ -57,12 +62,12 @@ $PostgreSQL: pgsql/doc/src/sgml/pltcl.sgml,v 2.38 2005/05/20 01:52:25 neilc Exp
     a user logged in as the database administrator.
    </para>
    <para>
-    The shared object for the <application>PL/Tcl</> and <application>PL/TclU</> call handlers is
+    The shared object code for the <application>PL/Tcl</> and
-    automatically built and installed in the
+    <application>PL/TclU</> call handlers is automatically built and
-    <productname>PostgreSQL</productname> 
+    installed in the <productname>PostgreSQL</productname> library
-    library directory if Tcl support is specified
+    directory if Tcl support is specified in the configuration step of
-    in the configuration step of the installation procedure.  To install
+    the installation procedure.  To install <application>PL/Tcl</>
-    <application>PL/Tcl</> and/or <application>PL/TclU</> in a particular database, use the
+    and/or <application>PL/TclU</> in a particular database, use the
     <command>createlang</command> program, for example
     <literal>createlang pltcl <replaceable>dbname</></literal> or
     <literal>createlang pltclu <replaceable>dbname</></literal>.