Restructure discussion of PL installation to emphasize createlang as the

recommended install procedure, rather than mentioning it as an afterthought.

diff --git a/doc/src/sgml/xplang.sgml b/doc/src/sgml/xplang.sgml
index 5c1352677747811cae92a3ebbb3f178159635581..8e72b9318988df93b777d3d0f9ea6bac0e738b7c 100644 (file)
--- a/doc/src/sgml/xplang.sgml
+++ b/doc/src/sgml/xplang.sgml
@@ -1,5 +1,5 @@
 
 
  
@@ -15,7 +15,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/xplang.sgml,v 1.11 2001/02/04 15:28:18 pete
    text. Instead, the task is passed to a special handler that knows
    the details of the language.  The handler could either do all the
    work of parsing, syntax analysis, execution, etc. itself, or it
-   could serve as a glue between
+   could serve as glue between
    Postgres and an existing implementation
    of a programming language.  The handler itself is a special
    programming language function compiled into a shared object and
@@ -24,33 +24,52 @@ $Header: /cvsroot/pgsql/doc/src/sgml/xplang.sgml,v 1.11 2001/02/04 15:28:18 pete
 
   
    Writing a handler for a new procedural language is outside the
-   scope of this manual.  Several procedural languages are available
-   in the Postgres distribution.
+   scope of this manual, although some information is provided in
+   the CREATE LANGUAGE reference page.  Several procedural languages are
+   available in the standard Postgres distribution.
   
 
   
    Installing Procedural Languages
 
+   
+    A procedural language must be installed into each
+    database where it is to be used.  But procedural languages installed in
+    the template1 database are automatically available in all
+    subsequently created databases. So the database administrator can
+    decide which languages are available in which databases, and can make
+    some languages available by default if he chooses.
+   
+
+   
+    For the languages supplied with the standard distribution, the
+    shell script createlang may be used instead
+    of carrying out the details by hand.  For example, to install PL/pgSQL
+    into the template1 database, use
+
+createlang plpgsql template1
+
+    The manual procedure described below is only recommended for
+    installing custom languages that createlang
+    does not know about.
+   
+
    
     </div>
<div class="diff rem">-     Procedural Language Installation</div>
<div class="diff add">+     <span class="marked">Manual </span>Procedural Language Installation</div>
<div class="diff ctx">     
 
     
      A procedural language is installed in the database in three
-     steps.  A procedural language must be installed into each
-     database where it is to be used.  Procedural languages defined in
-     the template1 database are automatically available in all
-     subsequently created databases. So the administrator can decide
-     which languages are available by default.
+     steps, which must be carried out by a database superuser.
     
 
     
      
       The shared object for the language handler must be compiled and
-      installed.  This works in the same way as building and
-      installing modules with regular user-defined C functions does;
-      see .
+      installed into an appropriate library directory.  This works in the same
+      way as building and installing modules with regular user-defined C
+      functions does; see .
      
     
 
@@ -84,18 +103,21 @@ CREATE TRUSTED PROCEDURAL LANGUAGE '
       executed inside the database backend, the TRUSTED
       flag should only be given for
       languages that do not allow access to database backends
-      internals or the filesystem. The languages PL/pgSQL and
-      PL/Tcl are known to be trusted.
+      internals or the filesystem. The languages PL/pgSQL,
+      PL/Tcl, and PL/Perl are known to be trusted; the language PL/TclU
+      should not be marked trusted.
      
     
    
 
    
     In a default Postgres installation, the
-    handler for the PL/pgSQL is built and installed into the
+    handler for the PL/pgSQL language is built and installed into the
     library directory. If Tcl/Tk support is configured
-    in, the handler for PL/Tcl is also built and installed in the same
-    location.
+    in, the handlers for PL/Tcl and PL/TclU are also built and installed in
+    the same location.  Likewise, the PL/Perl handler is built and installed
+    if Perl support is configured.  The createlang
+    script automates the two CREATE steps described above.
    
 
    
@@ -128,31 +150,6 @@ CREATE TRUSTED PROCEDURAL LANGUAGE 'plpgsql'
     
    
 
-   
-    For the languages supplied with the standard distribution, the
-    shell script createlang can be used instead
-    of carrying out the details manually.  To install PL/pgSQL into
-    the template1 database, use
-
-createlang plpgsql template1
-
-   
-
-     
-      PL handler functions have a special call interface that is
-      different from regular C language functions. One of the arguments
-      given to the handler is the object ID in the pg_proc
-      tables entry for the function that should be executed.
-      The handler examines various system catalogs to analyze the
-      functions call arguments and it's return data type. The source
-      text of the functions body is found in the prosrc attribute of
-      pg_proc.
-      Due to this, PL functions
-      can be overloaded like SQL language functions. There can be
-      multiple different PL functions having the same function name,
-      as long as the call arguments differ.
-     
-