Move PL docs to programmer's guide, "storage" chapter to admin guide,

clean up some things in the affected areas.

doc/src/sgml/admin.sgml

@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/admin.sgml,v 1.32 2001/02/03 19:03:26 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/Attic/admin.sgml,v 1.33 2001/02/04 15:28:18 petere Exp $
 -->
 
 <book id="admin">
@@ -31,6 +31,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/admin.sgml,v 1.32 2001/02/03 19:03:26
   &user-manag;
   &backup;
   &wal;
+  &storage;
   &recovery;
   &regress;
   &release;

doc/src/sgml/environ.sgml

@@ -1,62 +0,0 @@
-<Chapter Id="environ">
-<Title>Setting Up Your Environment</Title>
-
-<Para>
-     This section discusses how to set up
-     your own environment  so  that  you  can  use  frontend
-     applications.  We assume <ProductName>Postgres</ProductName> has already been 
-     successfully installed and started; refer to the Administrator's Guide
-and the installation  notes
-     for how to install Postgres.
-</Para>
-
-<Para>
-<ProductName>Postgres</ProductName> is a client/server application. As a user,
-you only need access to the client portions of the installation (an example
-of a client application is the interactive monitor <Application>psql</Application>).
-     For simplicity,
-     we will assume that <ProductName>Postgres</ProductName> has been installed in  the
-     directory  <FileName>/usr/local/pgsql</FileName>.   Therefore, wherever
-     you see the directory <FileName>/usr/local/pgsql</FileName> you  should
-     substitute  the name of the directory where <ProductName>Postgres</ProductName> is
-     actually installed.
-     All <ProductName>Postgres</ProductName> commands are installed  in  the  directory
-     <FileName>/usr/local/pgsql/bin</FileName>.   Therefore,  you should add
-     this directory to your shell command path.  If you  use
-     a variant of the Berkeley C shell, such as <Application>csh</Application> or <Application>tcsh</Application>,
-     you would add
-<ProgramListing>
-set path = ( /usr/local/pgsql/bin path )
-</ProgramListing>
-     in the <FileName>.login</FileName> file in your home directory.  If you  use
-     a  variant  of  the  Bourne  shell, such as <Application>sh</Application>, <Application>ksh</Application>, or
-     <Application>bash</Application>, then you would add
-<ProgramListing>
-$ PATH=/usr/local/pgsql/bin:$PATH
-$ export PATH
-</ProgramListing>
-     to the <FileName>.profile</FileName> file in your home directory.
-     From now on, we will assume that  you  have  added  the
-     <ProductName>Postgres</ProductName>  bin  directory to your path.  In addition, we
-     will make frequent reference to "setting a shell  
-     variable"  or  "setting an environment variable" throughout
-     this document.  If you did  not  fully  understand  the
-     last  paragraph  on  modifying  your  search  path, you
-     should consult the Unix manual pages that describe your
-     shell before going any further.
-</Para>
-
-<Para>
-If your site administrator has not set things up in the
-default  way,  you may have some more work to do.  For example, if the database
- server machine is a remote machine, you
-will need to set the <Acronym>PGHOST</Acronym> environment variable to the name
-of the database server machine.   The  environment  variable
-<Acronym>PGPORT</Acronym> may also have to be set.  The bottom line is this: if
-you try to start an application  program  and  it  complains
-that it cannot connect to the <Application>postmaster</Application>,
- you should immediately consult your site administrator to make sure that your
-environment is properly set up.
-</Para>
-
-</Chapter>

doc/src/sgml/filelist.sgml

@@ -1,4 +1,4 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/filelist.sgml,v 1.7 2001/02/03 19:03:26 petere Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/filelist.sgml,v 1.8 2001/02/04 15:28:18 petere Exp $ -->
 
 <!entity history    SYSTEM "history.sgml">
 <!entity info       SYSTEM "info.sgml">
@@ -8,6 +8,7 @@
 <!entity y2k        SYSTEM "y2k.sgml">
 
 <!-- tutorial -->
+<!entity advanced   SYSTEM "advanced.sgml">
 <!entity arch       SYSTEM "arch.sgml">
 <!entity intro      SYSTEM "intro.sgml">
 <!entity query      SYSTEM "query.sgml">
@@ -15,23 +16,16 @@
 <!entity start      SYSTEM "start.sgml">
 
 <!-- user's guide -->
-<!entity advanced   SYSTEM "advanced.sgml">
 <!entity array      SYSTEM "array.sgml">
 <!entity datatype   SYSTEM "datatype.sgml">
 <!entity datetime   SYSTEM "datetime.sgml">
-<!entity environ    SYSTEM "environ.sgml">
 <!entity func       SYSTEM "func.sgml">
 <!entity indices    SYSTEM "indices.sgml">
 <!entity inherit    SYSTEM "inherit.sgml">
 <!entity manage     SYSTEM "manage.sgml">
 <!entity mvcc       SYSTEM "mvcc.sgml">
 <!entity perform    SYSTEM "perform.sgml">
-<!entity plperl     SYSTEM "plperl.sgml">
-<!entity plsql      SYSTEM "plsql.sgml">
-<!entity pltcl      SYSTEM "pltcl.sgml">
-<!entity psql       SYSTEM "psql.sgml">
 <!entity queries    SYSTEM "queries.sgml">
-<!entity storage    SYSTEM "storage.sgml">
 <!entity syntax     SYSTEM "syntax.sgml">
 <!entity typeconv   SYSTEM "typeconv.sgml">
 <!entity keywords   SYSTEM "keywords.sgml">
@@ -51,6 +45,7 @@
 <!entity regress       SYSTEM "regress.sgml">
 <!entity release       SYSTEM "release.sgml">
 <!entity runtime       SYSTEM "runtime.sgml">
+<!entity storage       SYSTEM "storage.sgml">
 <!entity user-manag    SYSTEM "user-manag.sgml">
 <!entity wal           SYSTEM "wal.sgml">
 
@@ -79,6 +74,9 @@
 <!entity xplang     SYSTEM "xplang.sgml">
 <!entity xoper      SYSTEM "xoper.sgml">
 <!entity xtypes     SYSTEM "xtypes.sgml">
+<!entity plperl     SYSTEM "plperl.sgml">
+<!entity plsql      SYSTEM "plsql.sgml">
+<!entity pltcl      SYSTEM "pltcl.sgml">
 
 <!-- developer's guide -->
 <!entity arch-dev   SYSTEM "arch-dev.sgml">

doc/src/sgml/manage-ag.sgml

@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/manage-ag.sgml,v 2.11 2000/09/29 20:21:34 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/manage-ag.sgml,v 2.12 2001/02/04 15:28:18 petere Exp $
 -->
 
 <chapter id="managing-databases">
@@ -174,7 +174,7 @@ CREATE DATABASE <replaceable>name</> WITH LOCATION = '<replaceable>location</>'
      risk. To allow it, you must compile <productname>Postgres</> with
      the C preprocessor macro <literal>ALLOW_ABSOLUTE_DBPATHS</>
      defined. One way to do this is to run the compilation step like
-     this: <userinput>gmake COPT=-DALLOW_ABSOLUTE_DBPATHS all</>.
+     this: <userinput>gmake CPPFLAGS=-DALLOW_ABSOLUTE_DBPATHS all</>.
     </para>
    </note>
 

doc/src/sgml/manage.sgml

@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/manage.sgml,v 1.12 2000/10/08 19:44:01 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/Attic/manage.sgml,v 1.13 2001/02/04 15:28:18 petere Exp $
 -->
 
  <Chapter Id="manage">
@@ -256,22 +256,6 @@ mydb=> \q
      are denoted by "<literal>/* ... */</literal>".
 </Para>
 
-<Sect2>
-<Title>Database Privileges</Title>
-
-<Para>
-</para>
-</Sect2>
-
-<Sect2>
-<Title>Table Privileges</Title>
-
-<Para>
-TBD
-</Para>
-
-</Sect2>
-
 </Sect1>
      
 <Sect1 id="db-destroy">

doc/src/sgml/programmer.sgml

@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/programmer.sgml,v 1.33 2001/02/03 19:03:27 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/Attic/programmer.sgml,v 1.34 2001/02/04 15:28:18 petere Exp $
 
 PostgreSQL Programmer's Guide.
 -->
@@ -28,7 +28,9 @@ PostgreSQL Programmer's Guide.
    operators, aggregates, and both query language and programming
    language functions.  After a discussion of the
    <productname>PostgreSQL</productname> rule system, we discuss the
-   trigger and SPI interfaces.
+   trigger and SPI interfaces.  The third part documents the
+   procedural languages available in the
+   <productname>PostgreSQL</productname> distribution.
   </para>
 
   <para>
@@ -61,7 +63,6 @@ PostgreSQL Programmer's Guide.
   &xindex;
   &indexcost;
   &gist;
-  &xplang;
 
 <!-- reference -->
 
@@ -76,6 +77,15 @@ Disable it until we put in some info.
  &spi;
  </part>
 
+ <part id="programmer-pl">
+  <title>Procedural Languages</title>
+
+  &xplang;
+  &plsql;
+  &pltcl;
+  &plperl;
+ </part>
+
 <![%single-book;[
  &biblio;
 ]]>

doc/src/sgml/user.sgml

@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/user.sgml,v 1.27 2001/02/03 19:03:27 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/Attic/user.sgml,v 1.28 2001/02/04 15:28:18 petere Exp $
 -->
 
 <book id="user">
@@ -23,13 +23,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/user.sgml,v 1.27 2001/02/03 19:03:27
  &array;
  &indices;
  &inherit;
- &plsql;
- &pltcl;
- &plperl;
  &mvcc;
- &environ;
  &manage;
- &storage;
  &perform;
 
  <!-- appendices -->

doc/src/sgml/xplang.sgml

@@ -1,26 +1,31 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/xplang.sgml,v 1.10 2000/11/04 21:06:37 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/xplang.sgml,v 1.11 2001/02/04 15:28:18 petere Exp $
 -->
 
  <chapter id="xplang">
   <title id="xplang-title">Procedural Languages</title>
 
   <para>
-   <productname>Postgres</productname> supports
+   <productname>Postgres</productname> allows users to add new
-   the definition of procedural languages.
+   programming languages to be available for writing functions and
-   In the case of a function or trigger
+   procedures.  These are called <firstterm>procedural
-   procedure defined in a procedural language, the database has
+   languages</firstterm> (PL).  In the case of a function or trigger
+   procedure written in a procedural language, the database server has
    no built-in knowledge about how to interpret the function's source
-   text. Instead, the task is passed to
+   text. Instead, the task is passed to a special handler that knows
-   a handler that knows the details of the language. The
+   the details of the language.  The handler could either do all the
-   handler itself is a special programming language function
+   work of parsing, syntax analysis, execution, etc. itself, or it
-   compiled into a shared object
+   could serve as a <quote>glue</quote> between
-   and loaded on demand.
+   <productname>Postgres</productname> and an existing implementation
+   of a programming language.  The handler itself is a special
+   programming language function compiled into a shared object and
+   loaded on demand.
   </para>
 
   <para>
-   Writing a handler for a new procedural language (PL)
+   Writing a handler for a new procedural language is outside the
-   is outside the scope of this manual. 
+   scope of this manual.  Several procedural languages are available
+   in the <productname>Postgres</productname> distribution.
   </para>
 
   <sect1 id="xplang-install">
@@ -32,86 +37,107 @@ $Header: /cvsroot/pgsql/doc/src/sgml/xplang.sgml,v 1.10 2000/11/04 21:06:37 momj
     </title>
 
     <para>
-     A procedural language is installed in the database in three steps.
+     A procedural language is installed in the database in three
-     (For the languages supplied with the standard distribution, the
+     steps.  A procedural language must be installed into each
-     shell script <filename>createlang</filename> can be used instead
+     database where it is to be used.  Procedural languages defined in
-     of carrying out the details manually.)
+     the template1 database are automatically available in all
+     subsequently created databases. So the administrator can decide
+     which languages are available by default.
     </para>
 
-    <step performance="Required">
+    <step performance="required">
      <para>
-      The shared object for the language handler
+      The shared object for the language handler must be compiled and
-      must be compiled and installed. By default the
+      installed.  This works in the same way as building and
-      handler for PL/pgSQL is built and installed into the
+      installing modules with regular user-defined C functions does;
-      database library directory. If Tcl/Tk support is
+      see <xref linkend="dfunc">.
-      configured in, the handler for PL/Tcl is also built
-      and installed in the same location.
      </para>
     </step>
-    <step performance="Required">
+
+    <step performance="required">
      <para>
       The handler must be declared with the command
-      <programlisting>
+<synopsis>
 CREATE FUNCTION <replaceable>handler_function_name</replaceable> ()
     RETURNS OPAQUE AS
-    '<filename>path-to-shared-object</filename>' LANGUAGE 'C';
+    '<replaceable>path-to-shared-object</replaceable>' LANGUAGE 'C';
-      </programlisting>
+</synopsis>
-      The special return type of <acronym>OPAQUE</acronym> tells
+      The special return type of <type>OPAQUE</type> tells
       the database that this function does not return one of
-      the defined <acronym>SQL</acronym> datatypes and is not directly usable
+      the defined <acronym>SQL</acronym> data types and is not directly usable
       in <acronym>SQL</acronym> statements.
      </para>
     </step>
-    <step performance="Required">
+
+    <step performance="required">
      <para>
       The PL must be declared with the command
-      <programlisting>
+<synopsis>
-CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE '<replaceable>language-name</replaceable>'
+CREATE <optional>TRUSTED</optional> <optional>PROCEDURAL</optional> LANGUAGE '<replaceable>language-name</replaceable>'
     HANDLER <replaceable>handler_function_name</replaceable>
     LANCOMPILER '<replaceable>description</replaceable>';
-      </programlisting>
+</synopsis>
-      The optional keyword <acronym>TRUSTED</acronym> tells
+      The optional key word <token>TRUSTED</token> tells
       whether ordinary database users that have no superuser
       privileges should be allowed to use this language to create functions
       and trigger procedures. Since PL functions are
       executed inside the database backend, the <acronym>TRUSTED</acronym>
       flag should only be given for
-      languages that don't allow access to database backends
+      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.
      </para>
     </step>
    </procedure>
 
+   <para>
+    In a default <productname>Postgres</productname> installation, the
+    handler for the PL/pgSQL is built and installed into the
+    <quote>library</quote> directory. If Tcl/Tk support is configured
+    in, the handler for PL/Tcl is also built and installed in the same
+    location.
+   </para>
+
    <procedure>
     <title>Example</title>
-    <step performance="Required">
+
+    <step performance="required">
      <para>
       The following command tells the database where to find the 
       shared object for the PL/pgSQL language's call handler function.
 
-      <programlisting>
+<programlisting>
 CREATE FUNCTION plpgsql_call_handler () RETURNS OPAQUE AS
     '/usr/local/pgsql/lib/plpgsql.so' LANGUAGE 'C';
-      </programlisting>
+</programlisting>
      </para>
     </step>
 
     <step performance="Required">
     <para>
       The command
-      <programlisting>
+<programlisting>
 CREATE TRUSTED PROCEDURAL LANGUAGE 'plpgsql'
     HANDLER plpgsql_call_handler
     LANCOMPILER 'PL/pgSQL';
-      </programlisting>
+</programlisting>
+      then defines that the previously declared call handler function
+      should be invoked for functions and trigger procedures where the
+      language attribute is 'plpgsql'.
      </para>
+    </step>
+   </procedure>
+
+   <para>
+    For the languages supplied with the standard distribution, the
+    shell script <filename>createlang</filename> can be used instead
+    of carrying out the details manually.  To install PL/pgSQL into
+    the template1 database, use
+<programlisting>
+createlang plpgsql template1
+</programlisting>
+   </para>
 
-     <para>
-      then defines that the previously declared call handler
-      function should be invoked for functions and trigger procedures
-      where the language attribute is 'plpgsql'.
-     </para>
      <para>
       PL handler functions have a special call interface that is
       different from regular C language functions. One of the arguments
@@ -126,17 +152,9 @@ CREATE TRUSTED PROCEDURAL LANGUAGE 'plpgsql'
       multiple different PL functions having the same function name,
       as long as the call arguments differ.
      </para>
-     <para>
+
-      Procedural languages defined in the <filename>template1</filename>
-      database are automatically defined in all subsequently created
-      databases. So the database administrator can decide which
-      languages are available by default.
-     </para>
-    </step>
-   </procedure>
   </sect1>
 
- <!-- **** End of PL installation **** -->
 </chapter>
 
 <!-- Keep this comment at the end of the file