Re: [PATCHES] plpgsql documentation

2006-05-30 Thread Bruce Momjian

Patch applied.  Thanks.  Your documentation changes can be viewed in
five minutes using links on the developer's page,
http://www.postgresql.org/developer/testing.


---


Chris Browne wrote:
 An article at WebProNews quoted from the PG docs as to the merits of
 stored procedures.  I have added a bit more material on their merits,
 as well as making a few changes to improve the introductions to
 PL/Perl and PL/Tcl.
 
 Index: plperl.sgml
 ===
 RCS file: /projects/cvsroot/pgsql/doc/src/sgml/plperl.sgml,v
 retrieving revision 2.52
 diff -c -u -r2.52 plperl.sgml
 --- plperl.sgml   10 Mar 2006 19:10:48 -  2.52
 +++ plperl.sgml   25 May 2006 22:38:45 -
 @@ -17,6 +17,12 @@
 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 quotestring
 +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
 literalcreatelang plperl replaceabledbname//literal.
 Index: plpgsql.sgml
 ===
 RCS file: /projects/cvsroot/pgsql/doc/src/sgml/plpgsql.sgml,v
 retrieving revision 1.88
 diff -c -u -r1.88 plpgsql.sgml
 --- plpgsql.sgml  10 Mar 2006 19:10:48 -  1.88
 +++ plpgsql.sgml  25 May 2006 22:38:46 -
 @@ -155,21 +155,36 @@
  
  para
   That means that your client application must send each query to
 - the database server, wait for it to be processed, receive the
 - results, do some computation, then send other queries to the
 - server. All this incurs interprocess communication and may also
 - incur network overhead if your client is on a different machine
 - than the database server.
 + the database server, wait for it to be processed, receive and
 + process the results, do some computation, then send further
 + queries to the server.  All this incurs interprocess
 + communication and will also incur network overhead if your client
 + is on a different machine than the database server.
  /para
  
  para
 - With applicationPL/pgSQL/application you can group a block of 
 computation and a
 - series of queries emphasisinside/emphasis the
 - database server, thus having the power of a procedural
 - language and the ease of use of SQL, but saving lots of
 - time because you don't have the whole client/server
 - communication overhead. This can make for a
 - considerable performance increase.
 + With applicationPL/pgSQL/application you can group a block of
 + computation and a series of queries emphasisinside/emphasis
 + the database server, thus having the power of a procedural
 + language and the ease of use of SQL, but with considerable
 + savings because you don't have the whole client/server
 + communication overhead.
 +/para
 +itemizedlist
 +
 + listitempara Elimination of additional round trips between
 + client and server /para/listitem
 +
 + listitempara Intermediate results that the client does not
 + need do not need to be marshalled or transferred between server
 + and client /para/listitem
 +
 + listitempara 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
 Index: pltcl.sgml
 ===
 RCS file: /projects/cvsroot/pgsql/doc/src/sgml/pltcl.sgml,v
 retrieving revision 2.39
 diff -c -u -r2.39 pltcl.sgml
 --- pltcl.sgml10 Mar 2006 19:10:48 -  2.39
 +++ pltcl.sgml25 May 2006 22:38:46 -
 @@ -25,22 +25,27 @@
 titleOverview/title
  
 para
 -PL/Tcl offers most of the capabilities a function
 -writer has in the C language, except for some restrictions.
 +PL/Tcl offers most of the capabilities a function writer has in
 +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
 -Tcl interpreter. In addition to the limited command set of safe Tcl, only
 -a few commands are available to access the database via SPI and to raise
 -messages via functionelog()/. There is no way to access internals of 
 the
 -database server or to gain OS-level access under the permissions of the
 -

[PATCHES] plpgsql documentation

2006-05-25 Thread Chris Browne
An article at WebProNews quoted from the PG docs as to the merits of
stored procedures.  I have added a bit more material on their merits,
as well as making a few changes to improve the introductions to
PL/Perl and PL/Tcl.

Index: plperl.sgml
===
RCS file: /projects/cvsroot/pgsql/doc/src/sgml/plperl.sgml,v
retrieving revision 2.52
diff -c -u -r2.52 plperl.sgml
--- plperl.sgml 10 Mar 2006 19:10:48 -  2.52
+++ plperl.sgml 25 May 2006 22:38:45 -
@@ -17,6 +17,12 @@
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 quotestring
+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
literalcreatelang plperl replaceabledbname//literal.
Index: plpgsql.sgml
===
RCS file: /projects/cvsroot/pgsql/doc/src/sgml/plpgsql.sgml,v
retrieving revision 1.88
diff -c -u -r1.88 plpgsql.sgml
--- plpgsql.sgml10 Mar 2006 19:10:48 -  1.88
+++ plpgsql.sgml25 May 2006 22:38:46 -
@@ -155,21 +155,36 @@
 
 para
  That means that your client application must send each query to
- the database server, wait for it to be processed, receive the
- results, do some computation, then send other queries to the
- server. All this incurs interprocess communication and may also
- incur network overhead if your client is on a different machine
- than the database server.
+ the database server, wait for it to be processed, receive and
+ process the results, do some computation, then send further
+ queries to the server.  All this incurs interprocess
+ communication and will also incur network overhead if your client
+ is on a different machine than the database server.
 /para
 
 para
- With applicationPL/pgSQL/application you can group a block of 
computation and a
- series of queries emphasisinside/emphasis the
- database server, thus having the power of a procedural
- language and the ease of use of SQL, but saving lots of
- time because you don't have the whole client/server
- communication overhead. This can make for a
- considerable performance increase.
+ With applicationPL/pgSQL/application you can group a block of
+ computation and a series of queries emphasisinside/emphasis
+ the database server, thus having the power of a procedural
+ language and the ease of use of SQL, but with considerable
+ savings because you don't have the whole client/server
+ communication overhead.
+/para
+itemizedlist
+
+ listitempara Elimination of additional round trips between
+ client and server /para/listitem
+
+ listitempara Intermediate results that the client does not
+ need do not need to be marshalled or transferred between server
+ and client /para/listitem
+
+ listitempara 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
Index: pltcl.sgml
===
RCS file: /projects/cvsroot/pgsql/doc/src/sgml/pltcl.sgml,v
retrieving revision 2.39
diff -c -u -r2.39 pltcl.sgml
--- pltcl.sgml  10 Mar 2006 19:10:48 -  2.39
+++ pltcl.sgml  25 May 2006 22:38:46 -
@@ -25,22 +25,27 @@
titleOverview/title
 
para
-PL/Tcl offers most of the capabilities a function
-writer has in the C language, except for some restrictions.
+PL/Tcl offers most of the capabilities a function writer has in
+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
-Tcl interpreter. In addition to the limited command set of safe Tcl, only
-a few commands are available to access the database via SPI and to raise
-messages via functionelog()/. There is no way to access internals of 
the
-database server or to gain OS-level access under the permissions of the
-productnamePostgreSQL/productname server process, as a C function can 
do.
-Thus, any unprivileged database user may be
-permitted to use this language.
+One compelling emphasisgood/emphasis restriction is that
+everything is executed from within the safety of the context of a
+Tcl interpreter.  In addition to the limited command set of safe
+Tcl, only a few commands are