Update installation instructions and put mostly everything in one place.

Also, some editing in PL/Perl and PL/Python chapters.

9 files changed, 617 insertions, 702 deletions

diff --git a/doc/src/sgml/charset.sgml b/doc/src/sgml/charset.sgml
index a4093a2382f..febe4d37326 100644
--- a/doc/src/sgml/charset.sgml
+++ b/doc/src/sgml/charset.sgml
@@ -1,4 +1,4 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/charset.sgml,v 2.27 2002/08/14 02:45:09 ishii Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/charset.sgml,v 2.28 2002/09/18 20:09:31 petere Exp $ -->
 
 <chapter id="charset">
  <title>Localization</>
@@ -890,30 +890,6 @@ RESET CLIENT_ENCODING;
    </sect2>
 
    <sect2>
-    <title>About Unicode</title>
-
-    <indexterm><primary>Unicode</></>
-
-    <para>
-     An automatic encoding translation between Unicode and other
-     encodings has been supported since <productname>PostgreSQL</> 7.1.
-     For 7.1 it was not enabled by default.
-     To enable this feature, run configure with the
-     <option>--enable-unicode-conversion</option> option. Note that this requires
-     the <option>--enable-multibyte</option> option also.
-    </para>
-    <para>
-    For 7.2, <option>--enable-unicode-conversion</option> is not necessary.
-    The Unicode conversion functionality is automatically enabled
-    if <option>--enable-multibyte</option> is specified.
-    </para>
-    <para>
-    For 7.3, <option>--enable-unicode-conversion</option> nor
-    <option>--enable-multibyte</option> is needed.
-    </para>
-   </sect2>
-
-   <sect2>
     <title>What happens if the translation is not possible?</title>
 
     <para>
diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml
index dc4b2649c13..6e1d76522a1 100644
--- a/doc/src/sgml/client-auth.sgml
+++ b/doc/src/sgml/client-auth.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.37 2002/09/14 18:35:46 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.38 2002/09/18 20:09:31 petere Exp $
 -->
 
 <chapter id="client-authentication">
@@ -583,10 +583,9 @@ local   db1,db2,@demodbs  all                                       md5
 
    <para>
     In order to use <productname>Kerberos</>, support for it must be
-    enabled at build time. Both Kerberos 4 and 5 are supported
-    (<literal>./configure --with-krb4</> or <literal>./configure
-    --with-krb5</> respectively), although only one version can be
-    supported in any one build.
+    enabled at build time.  See <xref linkend="installation"> for more
+    information.  Both Kerberos 4 and 5 are supported, but only one
+    version can be supported in any one build.
    </para>
 
    <para>
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index 69aa6737f6b..be27b9dddf8 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -1,4 +1,4 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v 1.80 2002/09/08 02:33:08 momjian Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v 1.81 2002/09/18 20:09:31 petere Exp $ -->
 
 <chapter id="installation">
  <title><![%standalone-include[<productname>PostgreSQL</>]]>
@@ -47,7 +47,9 @@ su - postgres
   </para>
 
   <para>
-   The following prerequisites exist for building <productname>PostgreSQL</>:
+   The following software packages are required for building
+   <productname>PostgreSQL</>:
+
    <itemizedlist>
     <listitem>
      <para>
@@ -106,46 +108,192 @@ su - postgres
     <listitem>
      <para>
       <indexterm>
-       <primary>flex</primary>
-      </indexterm>
-      <indexterm>
-       <primary>bison</primary>
-      </indexterm>
-      <indexterm>
-       <primary>yacc</primary>
+       <primary>installation</primary>
+       <secondary>on Windows</secondary>
       </indexterm>
 
-      <acronym>GNU</> <application>Flex</> and <application>Bison</> are
-      needed to build from scratch, but they are
-      <emphasis>not</> required when building from a released source
-      package because pre-generated output files are included in released
-      packages. You will
-      need these programs only when building from a CVS tree or if you
-      changed the actual scanner and parser definition files. If
-      you need them, be sure to get <application>Flex</> 2.5.4 or
-      later and <application>Bison</> 1.28 or later. Other <application>yacc</>
-      programs can sometimes be used, but doing so requires extra
-      effort and is not recommended. Other <application>lex</> programs will
-      definitely not work.
+      To build on <productname>Windows NT</> or <productname>Windows
+      2000</> you need the <productname>Cygwin</> and
+      <productname>cygipc</> packages. See the file
+      <filename>doc/FAQ_MSWIN</> for details.
+     </para>
+    </listitem>
+   </itemizedlist>
+  </para>
+
+  <para>
+   The following packages are optional.  They are not required in the
+   default configuration, but they are needed when certain build
+   options are enabled, as explained below.
+
+   <itemizedlist>
+    <listitem>
+     <para>
+      To build the server programming language PL/Perl you need a full
+      Perl installation, including the <filename>libperl</filename>
+      library and the header files.  Since PL/Perl is a shared
+      library, the <indexterm><primary>libperl</primary></indexterm>
+      <filename>libperl</filename> library must be a shared library
+      also on most platforms.  At the time of this writing, this is
+      almost never the case in prebuilt Perl packages.
+     </para>
+
+     <para>
+      If this difficulty arises in your situation, a message like this
+      will appear during the build to point out this fact:
+<screen>
+*** Cannot build PL/Perl because libperl is not a shared library.
+*** You might have to rebuild your Perl installation.  Refer to
+*** the documentation for details.
+</screen>
+      (If you don't follow the onscreen output you will merely notice
+      the the PL/Perl library object will not be installed.)  If you
+      see this, you will have to re-build and install
+      <productname>Perl</productname> manually to be able to build
+      PL/Perl.  During the configuration process for
+      <productname>Perl</productname>, request a shared library.
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      To build the Python interface module or the PL/Python server
+      programming language, you need a Python installation, including
+      the header files.
+     </para>
+
+     <para>
+      Since PL/Python is a shared library, the
+      <indexterm><primary>libpython</primary></indexterm>
+      <filename>libpython</filename> library must be a shared library
+      also on most platforms.  This is not the case in a default
+      Python installation.  If after building and installing you have
+      a file called <filename>plpython.so</filename> (possibly a
+      different extension), then everything went well.  Otherwise you
+      should have seen a notice like this flying by:
+<screen>
+*** Cannot build PL/Python because libpython is not a shared library.
+*** You might have to rebuild your Python installation.  Refer to
+*** the documentation for details.
+</screen>
+      That means you have to rebuild (part of) your Python
+      installation to supply this shared library.
+     </para>
+
+     <para>
+      The catch is that the Python distribution or the Python
+      maintainers do not provide any direct way to do this.  The
+      closest thing we can offer you is the information in <ulink
+      url="http://www.python.org/doc/FAQ.html#3.30">Python FAQ
+      3.30</ulink>.  On some operating systems you don't really have
+      to build a shared library, but then you will have to convince
+      the PostgreSQL build system of this.  Consult the
+      <filename>Makefile</filename> in the
+      <filename>src/pl/plpython</filename> directory for details.
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      If you want to build Tcl or Tk components (clients and the
+      PL/Tcl language) you of course need a Tcl installation.
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      To build the JDBC driver, you need
+      <application>Ant</application> 1.5 or higher and a
+      <acronym>JDK</acronym>.  <application>Ant</application> is a
+      special tool for building Java-based packages.  It can be
+      downloaded from the <ulink
+      url="http://jakarta.apache.org/ant/index.html"><application>Ant</application>
+      web site</ulink>.
+     </para>
+
+     <para>
+      If you have several Java compilers installed, it depends on the
+      Ant configuration which one gets used.  Precompiled
+      <application>Ant</application> distributions are typically set
+      up to read a file <filename>.antrc</filename> in the current
+      user's home directory for configuration.  For example, to use a
+      different <acronym>JDK</acronym> than the default, this may
+      work:
+<programlisting>
+JAVA_HOME=/usr/local/sun-jdk1.3
+JAVACMD=$JAVA_HOME/bin/java
+</programlisting>
+     </para>
+
+     <note>
+      <para>
+       Do not try to build the driver by calling
+       <command>ant</command> or even <command>javac</command>
+       directly.  This will not work.  Run <command>gmake</command>
+       normally as described below.
+      </para>
+     </note>
+    </listitem>
+
+    <listitem>
+     <para>
+      To enable Native Language Support (<acronym>NLS</acronym>), that
+      is, the ability to display a program's messages in a language
+      other than English, you need an implementation of the Gettext
+      <acronym>API</acronym>.  Some operating systems have this
+      built-in (e.g., <systemitem class="osname">Linux</>, <systemitem
+      class="osname">NetBSD</>, <systemitem
+      class="osname">Solaris</>), for other systems you can download
+      an add-on package from here: <ulink
+      url="http://www.postgresql.org/~petere/gettext.html" ></ulink>.
+      If you are using the <application>gettext</> implementation in
+      the GNU C library then you will additionally need the
+      <productname>GNU Gettext</productname> package for some utility
+      programs.  For any of the other implementations you will not
+      need it.
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      Kerberos, OpenSSL, or PAM, if you want to support
+      authentication using these services.
      </para>
     </listitem>
+   </itemizedlist>
+  </para>
 
+  <para>
+   If you are build from a CVS tree instead of using a released source
+   package, or if you want to do development, you also need the
+   following packages:
+
+   <itemizedlist>
     <listitem>
      <para>
       <indexterm>
-       <primary>installation</primary>
-       <secondary>on Windows</secondary>
+       <primary>flex</primary>
+      </indexterm>
+      <indexterm>
+       <primary>bison</primary>
+      </indexterm>
+      <indexterm>
+       <primary>yacc</primary>
       </indexterm>
 
-      To build on <productname>Windows NT</> or <productname>Windows
-      2000</> you need the <productname>Cygwin</> and
-      <productname>cygipc</> packages. See the file
-      <filename>doc/FAQ_MSWIN</> for details.
+      <acronym>GNU</> <application>Flex</> and <application>Bison</>
+      are needed to build a CVS checkout or if you changed the actual
+      scanner and parser definition files. If you need them, be sure
+      to get <application>Flex</> 2.5.4 or later and
+      <application>Bison</> 1.28 or later. Other <application>yacc</>
+      programs can sometimes be used, but doing so requires extra
+      effort and is not recommended. Other <application>lex</>
+      programs will definitely not work.
      </para>
     </listitem>
    </itemizedlist>
   </para>
- 
+
   <para>
    If you need to get a <acronym>GNU</acronym> package, you can find
    it at your local <acronym>GNU</acronym> mirror site (see <ulink
@@ -156,12 +304,13 @@ su - postgres
 
   <para>
    Also check that you have sufficient disk space. You will need about
-   30 MB for the source tree during compilation and about 10 MB for the
-   installation directory. An empty database cluster takes about 20 MB, databases
-   take about five times the amount of space that a flat text file
-   with the same data would take. If you are going to run the
-   regression tests you will temporarily need an extra 20 MB. Use the
-   <command>df</command> command to check for disk space.
+   65 MB for the source tree during compilation and about 15 MB for
+   the installation directory. An empty database cluster takes about
+   25 MB, databases take about five times the amount of space that a
+   flat text file with the same data would take. If you are going to
+   run the regression tests you will temporarily need up to an extra
+   90 MB. Use the <command>df</command> command to check for disk
+   space.
   </para>
  </sect1>
 
@@ -335,8 +484,10 @@ su - postgres
 </screen>
     This script will run a number of tests to guess values for various
     system dependent variables and detect some quirks of your
-    operating system, and finally will create several files in the build
-    tree to record what it found.
+    operating system, and finally will create several files in the
+    build tree to record what it found.  (You can also run
+    <filename>configure</filename> in a directory outside the source
+    tree if you want to keep the build directory separate.)
    </para>
 
    <para>
@@ -480,9 +631,7 @@ su - postgres
        prefix, the documentation will be installed in
        <filename>/usr/local/doc/postgresql</filename>, but if the
        prefix is <filename>/opt/postgres</filename>, then it will be
-       in <filename>/opt/postgres/doc</filename>.  Second, the
-       installation layout of the C and C++ header files has been
-       reorganized in the 7.2 release.  The public header files of the
+       in <filename>/opt/postgres/doc</filename>.  The public C header files of the
        client interfaces are installed into
        <varname>includedir</varname> and are namespace-clean.  The
        internal header files and the server header files are installed
@@ -537,27 +686,11 @@ su - postgres
        <listitem>
         <para>
          Enables single-byte character set recode support. See
-         <![%standalone-include[the <citetitle>Administrator's Guide</citetitle>]]>
-         <![%standalone-ignore[<xref linkend="recode">]]> about this feature.
-        </para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term><option>--enable-multibyte</option></term>
-       <listitem>
-        <para>
-         Allows the use of multibyte character encodings (including Unicode)
-         and character set encoding conversion. Read 
-         <![%standalone-include[the <citetitle>Administrator's Guide</citetitle>]]>
-         <![%standalone-ignore[<xref linkend="multibyte">]]>
-         for details.
-        </para>
-
-        <para>
-         Note that some interfaces (such as Tcl or Java) expect all character
-         strings to be in Unicode, so this option will be required to correctly
-         support these interfaces.
+         <![%standalone-include[the <citetitle>Administrator's
+         Guide</citetitle>]]> <![%standalone-ignore[<xref
+         linkend="recode">]]> about this feature.  Note that a more
+         general form of character set conversion is supported in the
+         default configuration; this feature is obsolete.
         </para>
        </listitem>
       </varlistentry>
@@ -566,38 +699,22 @@ su - postgres
        <term><option>--enable-nls<optional>=<replaceable>LANGUAGES</replaceable></optional></option></term>
        <listitem>
         <para>
-         Enables Native Language Support (<acronym>NLS</acronym>), that is, the ability
-         to display a program's messages in a language other than
-         English.  <replaceable>LANGUAGES</replaceable> is a space
-         separated list of codes of the languages that you want
-         supported, for example <literal>--enable-nls='de fr'</>.
-         (The intersection between your list and the set
-         of actually provided translations will be computed
-         automatically.)  If you do not specify a list, then all available
-         translations are installed.
+         Enables Native Language Support (<acronym>NLS</acronym>),
+         that is, the ability to display a program's messages in a
+         language other than English.
+         <replaceable>LANGUAGES</replaceable> is a space separated
+         list of codes of the languages that you want supported, for
+         example <literal>--enable-nls='de fr'</>.  (The intersection
+         between your list and the set of actually provided
+         translations will be computed automatically.)  If you do not
+         specify a list, then all available translations are
+         installed.
         </para>
 
-        <comment>
-         The list of provided translations should be shown somewhere.
-        </comment>
-
         <para>
          To use this option, you will need an implementation of the
-         <application>gettext</> API.  Some operating systems have this built-in
-         (e.g., <systemitem class="osname">Linux</>, <systemitem class="osname">NetBSD</>, <systemitem class="osname">Solaris</>), for other systems you can download
-         an add-on package from here:  <ulink
-         url="http://www.postgresql.org/~petere/gettext.html"
-         ></ulink>.  If
-         you are using the <application>gettext</> implementation in the GNU C library
-         then you will additionally need the <productname>GNU gettext</productname> package for
-         some utility programs.  For any of the other implementations
-         you will not need it.
+         <application>gettext</> API; see above.
         </para>
-
-        <comment>
-         The download location should be moved.
-        </comment>
-
        </listitem>
       </varlistentry>
 
@@ -617,15 +734,6 @@ su - postgres
       </varlistentry>
 
       <varlistentry>
-       <term><option>--with-CXX</option></term>
-       <listitem>
-        <para>
-         Build the C++ interface library.
-        </para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
        <term><option>--with-perl</option></term>
        <listitem>
         <para>
@@ -638,9 +746,9 @@ su - postgres
        <term><option>--with-python</option></term>
        <listitem>
         <para>
-         Build the Python interface module. You need to have root
-         access to be able to install the Python module at its default
-         place
+         Build the Python interface module and the PL/Python
+         server-side language. You need to have root access to be able
+         to install the Python module at its default place
          (<filename>/usr/lib/python<replaceable>x</>.<replaceable>y</></>).
          To be able to use this option, you must have Python installed
          and your system needs to support shared libraries. If you
@@ -692,68 +800,11 @@ su - postgres
       </varlistentry>
 
       <varlistentry>
-       <term><option>--enable-odbc</option></term>
-       <listitem>
-        <para>
-         Build the ODBC driver.  By default, the driver will be independent
-         of a driver manager.  To work better with a driver manager already
-         installed on your system, use one of the following options in addition
-         to this one.  More information can be found in the
-         <citetitle>Programmer's Guide</citetitle>.
-        </para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term><option>--with-iodbc</option></term>
-       <listitem>
-        <para>
-         Build the ODBC driver for use with <productname>iODBC</>.
-        </para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term><option>--with-unixodbc</option></term>
-       <listitem>
-        <para>
-         Build the ODBC driver for use with <productname>unixODBC</>.
-        </para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term><option>--with-odbcinst=<replaceable>DIRECTORY</></option></term>
-       <listitem>
-        <para>
-         Specifies the directory where the ODBC driver will expect its
-         <filename>odbcinst.ini</> configuration file. The default is
-         <filename>/usr/local/pgsql/etc</filename> or whatever you
-         specified as <option>--sysconfdir</option>. It should be
-         arranged that the driver reads the same file as the driver
-         manager.
-        </para>
-
-        <para>
-         If either the option <option>--with-iodbc</option> or the
-         option <option>--with-unixodbc</option> is used, this option
-         will be ignored because in that case the driver manager
-         handles the location of the configuration file.
-        </para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
        <term><option>--with-java</option></term>
        <listitem>
         <para>
          Build the <acronym>JDBC</acronym> driver and associated Java
-         packages.  This option requires
-         <application>Ant</application> to be installed (as well as a
-         <acronym>JDK</acronym>, of course).  Refer to the
-         <acronym>JDBC</acronym> driver documentation in the
-         <citetitle>Programmer's Guide</citetitle> for more
-         information.
+         packages.
         </para>
        </listitem>
       </varlistentry>
@@ -831,19 +882,6 @@ su - postgres
       </varlistentry>
 
       <varlistentry>
-       <term><option>--enable-syslog</option></term>
-       <listitem>
-        <para>
-         Enables the <productname>PostgreSQL</> server to use the
-         <systemitem>syslog</> logging facility. (Using this option does not mean
-         that you must log with <systemitem>syslog</> or even that it will be done
-         by default, it simply makes it possible to turn that option
-         on at run time.)
-        </para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
        <term><option>--without-readline</option></term>
        <listitem>
         <para>
@@ -917,20 +955,26 @@ su - postgres
       </varlistentry>
 
      </variablelist>
-   </para>
+    </para>
 
-   <para>
-    If you prefer a C or C++ compiler different from the one
-    <filename>configure</filename> picks then you can set the
-    environment variables <envar>CC</> or <envar>CXX</envar>,
-    respectively, to the program of your choice.  Similarly, you can
-    override the default compiler flags with the <envar>CFLAGS</envar>
-    and <envar>CXXFLAGS</envar> variables.  For example:
+    <para>
+     If you prefer a C compiler different from the one
+     <filename>configure</filename> picks then you can set the
+     environment variable <envar>CC</> to the program of your choice.
+     By default, <filename>configure</filename> will pick
+     <filename>gcc</filename> unless this is inappropriate for the
+     platform.  Similarly, you can override the default compiler flags
+     with the <envar>CFLAGS</envar> variable.
+    </para>
+
+    <para>
+     You can specify environment variables on the
+     <filename>configure</filename> command line, for example:
 <screen>
-<userinput>env CC=/opt/bin/gcc CFLAGS='-O2 -pipe' ./configure</>
+<userinput>./configure CC=/opt/bin/gcc CFLAGS='-O2 -pipe'</>
 </screen>
-   </para>
-  </step>
+    </para>
+   </step>
 
   <step>
    <title>Build</title>
@@ -1057,34 +1101,40 @@ All of PostgreSQL is successfully made. Ready to install.
 </screen>
     </para>
    </formalpara>
+  </step>
+  </procedure>
 
+  <formalpara>
+   <title>Uninstall:</title>
    <para>
     To undo the installation use the command <command>gmake
     uninstall</>. However, this will not remove any created directories.
    </para>
-  </step>
-  </procedure>
+  </formalpara>
 
-  <para>
-   After the installation you can make room by removing the built
-   files from the source tree with the <command>gmake clean</>
-   command. This will preserve the files made by the configure
-   program, so that you can rebuild everything with <command>gmake</>
-   later on. To reset the source tree to the state in which it was
-   distributed, use <command>gmake distclean</>. If you are going to
-   build for several platforms from the same source tree you must do
-   this and re-configure for each build.
-  </para>
+  <formalpara>
+   <title>Cleaning:</title>
+
+   <para>
+    After the installation you can make room by removing the built
+    files from the source tree with the command <command>gmake
+    clean</>. This will preserve the files made by the configure
+    program, so that you can rebuild everything with <command>gmake</>
+    later on. To reset the source tree to the state in which it was
+    distributed, use <command>gmake distclean</>. If you are going to
+    build for several platforms from the same source tree you must do
+    this and re-configure for each build.
+   </para>
+  </formalpara>
 
   <para>
-   If you perform a build and then discover that your configure options
-   were wrong, or if you change anything that configure investigates
-   (for example, you install GNU <application>Readline</>), then it's
-   a good idea to do <command>gmake distclean</> before reconfiguring
-   and rebuilding.  Without this, your changes in configuration choices
+   If you perform a build and then discover that your configure
+   options were wrong, or if you change anything that configure
+   investigates (for example, software upgrades), then it's a good
+   idea to do <command>gmake distclean</> before reconfiguring and
+   rebuilding.  Without this, your changes in configuration choices
    may not propagate everywhere they need to.
   </para>
-
  </sect1>
 
  <sect1 id="install-post">
@@ -1139,17 +1189,13 @@ setenv LD_LIBRARY_PATH /usr/local/pgsql/lib
     building.
    </para>
 
-<!--
    <para>
-    On Linux systems the following is the preferred method, but you
-    must have root access. Edit the file <filename>/etc/ld.so.conf</>
-    to add a line
-<programlisting>
-<filename>/usr/local/pgsql/lib</>
-</programlisting>
-    Then run command <command>/sbin/ldconfig</>.
+    On <systemitem class="osname">Cygwin</systemitem>, put the library
+    directory on the <envar>PATH</envar> or move the
+    <filename>.dll</filename> files into the <filename>bin/</filename>
+    directory.
    </para>
--->
+
    <para>
     If in doubt, refer to the manual pages of your system (perhaps
     <command>ld.so</command> or <command>rld</command>). If you later
@@ -1194,14 +1240,21 @@ libpq.so.2.1: cannot open shared object file: No such file or directory
 
    <para>
     If you installed into <filename>/usr/local/pgsql</> or some other
-    location that is not searched for programs by default, you need to
+    location that is not searched for programs by default, you should
     add <filename>/usr/local/pgsql/bin</> (or whatever you set
     <option><literal>--bindir</></> to in <xref linkend="configure">)
-    into your <envar>PATH</>. To do this, add the following to your
-    shell start-up file, such as <filename>~/.bash_profile</> (or
-    <filename>/etc/profile</>, if you want it to affect every user):
+    into your <envar>PATH</>.  Strictly speaking, this is not
+    necessary, but it will make the use of PostgreSQL much more
+    convenient.
+   </para>
+
+   <para>
+    To do this, add the following to your shell start-up file, such as
+    <filename>~/.bash_profile</> (or <filename>/etc/profile</>, if you
+    want it to affect every user):
 <programlisting>
 PATH=/usr/local/pgsql/bin:$PATH
+export PATH
 </programlisting>
     If you are using <command>csh</> or <command>tcsh</>, then use this command:
 <programlisting>
@@ -1216,9 +1269,11 @@ set path = ( /usr/local/pgsql/bin $path )
     </indexterm>
     To enable your system to find the <application>man</>
     documentation, you need to add a line like the following to a
-    shell start-up file:
+    shell start-up file unless you installed into a location that is
+    searched by default.
 <programlisting>
 MANPATH=/usr/local/pgsql/man:$MANPATH
+export MANPATH
 </programlisting>
    </para>
 
diff --git a/doc/src/sgml/jdbc.sgml b/doc/src/sgml/jdbc.sgml
index c77817d16a4..69220dd59c9 100644
--- a/doc/src/sgml/jdbc.sgml
+++ b/doc/src/sgml/jdbc.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/jdbc.sgml,v 1.36 2002/03/22 19:20:11 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/Attic/jdbc.sgml,v 1.37 2002/09/18 20:09:31 petere Exp $
 -->
 
  <chapter id="jdbc">
@@ -51,92 +51,34 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/jdbc.sgml,v 1.36 2002/03/22 19:20:11
    </para>
 
    <para>
-    Alternatively you can build the driver from source.  Although you 
-    should only need to do this if you are making changes to the source
-    code.
+    Alternatively you can build the driver from source, but you
+    should only need to do this if you are making changes to the
+    source code.  For details, refer to the PostgreSQL installation
+    instructions.  After installation, the driver should be found in
+    <filename><replaceable>PREFIX</>/share/java/postgresql.jar</filename>.
+    The resulting driver will be built for the version of Java you are
+    running.  If you build with a 1.1 JDK you will build a version
+    that supports the JDBC 1 specification, if you build with a Java 2
+    JDK (e.g., JDK 1.2 or JDK 1.3) you will build a version that
+    supports the JDBC 2 specification.
    </para>
-
-   <para>
-    Starting with <productname>PostgreSQL</productname> version 7.1,
-    the <acronym>JDBC</acronym> driver is built using
-    <application>Ant</application>, a special tool for building
-    Java-based packages.  You should download
-    <application>Ant</application> from the <ulink
-    url="http://jakarta.apache.org/ant/index.html"><application>Ant</application>
-    web site</ulink> and install it before proceeding.  Precompiled
-    <application>Ant</application> distributions are typically set up
-    to read a file <filename>.antrc</filename> in the current user's
-    home directory for configuration.  For example, to use a different
-    <acronym>JDK</acronym> than the default, this may work:
-<programlisting>
-JAVA_HOME=/usr/local/sun-jdk1.3
-JAVACMD=$JAVA_HOME/bin/java
-</programlisting>
-   </para>
-
-   <para>
-    To build the driver, add the <option>--with-java</option> option to your
-    <filename>configure</filename> command line, e.g.,
-<screen>
-<prompt>$</prompt> <userinput>./configure --prefix=<replaceable>xxx</replaceable> --with-java ...</userinput>
-</screen>
-    This will build and install the driver along with the rest of the
-    <productname>PostgreSQL</productname> package when you issue the
-    <literal>make/gmake</literal> and <literal>make/gmake install</literal>
-    commands.  If you only want to build the driver and not the rest
-    of <productname>PostgreSQL</productname>, change into the
-    directory <filename
-    class="directory">src/interfaces/jdbc</filename> and issue the
-    respective <literal>make/gmake</literal> command there.  Refer to the
-    <productname>PostgreSQL</productname> installation instructions
-    for more information about the configuration and build process.
-   </para>
-
-   <para>When building the driver from source the jar file that is created
-    will be named <filename>postgresql.jar</filename>.  The build will 
-    create this file in the <filename>src/interfaces/jdbc/jars</filename>
-    directory.  The resulting driver will be built for the version of 
-    Java you are running.  If you build with a 1.1 JDK you will build
-    a version that supports the jdbc1 specification, if you build with a 
-    Java2 JDK (i.e. JDK1.2 or JDK1.3) you will build a version that 
-    supports the jdbc2 specification. 
-   </para>
- 
-   <note>
-    <para>
-     Do not try to build the driver by calling <command>javac</command> 
-     directly, as the driver uses some dynamic loading techniques for
-     performance reasons, and <command>javac</command> cannot cope.
-     Do not try to run <command>ant</command> directly either, because
-     some configuration information is communicated through the
-     makefiles.  Running <command>ant</command> directly without
-     providing these parameters will result in a broken driver.
-    </para>
-   </note>
   </sect2>
 
   <sect2 id="jdbc-classpath">
    <title>Setting up the Class Path</title>
 
    <para>
-    To use the driver, the jar archive (named
+    To use the driver, the JAR archive (named
     <filename>postgresql.jar</filename> if you built from source, otherwise
     it will likely be named <filename>jdbc7.2-1.1.jar</filename> or 
-    <filename>jdbc7.2-1.2.jar</filename> for the jdbc1 and jdbc2 versions
+    <filename>jdbc7.2-1.2.jar</filename> for the JDBC 1 and JDBC 2 versions
     respectively)
     needs to be included in the
     class path, either by putting it in the <envar>CLASSPATH</envar>
     environment variable, or by using flags on the
-    <command>java</command> command line.  By default, the jar archive
-    is installed in the directory <filename
-    class="directory">/usr/local/pgsql/share/java</filename>.  You may
-    have it in a different directory if you used the
-    <option>--prefix</option> option when you ran
-    <filename>configure</filename>, or if you are using a binary distribution
-    that places it in some different location.
+    <command>java</command> command line.
    </para>
 
-   <informalexample>
     <para>
      For instance, I have an application that uses the
      <acronym>JDBC</acronym> driver to access a large database
@@ -163,7 +105,6 @@ java Finder
      Loading the driver from within the application is covered in
      <xref linkend="jdbc-use">.
     </para>
-   </informalexample>
   </sect2>
 
   <sect2 id="jdbc-prepare">
@@ -183,7 +124,7 @@ java Finder
     Also, the client authentication setup in the
     <filename>pg_hba.conf</filename> file may need to be configured.
     Refer to the <citetitle>Administrator's Guide</citetitle> for
-    details.  The <acronym>JDBC</acronym> Driver supports trust,
+    details.  The <acronym>JDBC</acronym> Driver supports the trust,
     ident, password, md5, and crypt authentication methods.
    </para>
   </sect2>
diff --git a/doc/src/sgml/maintenance.sgml b/doc/src/sgml/maintenance.sgml
index 9793cd93503..939eba14237 100644
--- a/doc/src/sgml/maintenance.sgml
+++ b/doc/src/sgml/maintenance.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v 1.17 2002/06/23 03:51:55 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v 1.18 2002/09/18 20:09:32 petere Exp $
 -->
 
 <chapter id="maintenance">
@@ -424,14 +424,13 @@ VACUUM
 
   <para>
    The simplest production-grade approach to managing log output is to
-   send it all to <application>syslog</> and let <application>syslog</>
-   deal with file rotation. To do this, make sure
-   <productname>PostgreSQL</> was built with the
-   <option>--enable-syslog</> configure option, and set
+   send it all to <application>syslog</> and let
+   <application>syslog</> deal with file rotation. To do this, set
    <literal>syslog</> to 2 (log to syslog only) in
    <filename>postgresql.conf</>. Then you can send a
-   <literal>SIGHUP</literal> signal to the <application>syslog</> daemon
-   whenever you want to force it to start writing a new log file.
+   <literal>SIGHUP</literal> signal to the <application>syslog</>
+   daemon whenever you want to force it to start writing a new log
+   file.
   </para>
 
   <para>
diff --git a/doc/src/sgml/plperl.sgml b/doc/src/sgml/plperl.sgml
index c04ff95d929..97981bf603e 100644
--- a/doc/src/sgml/plperl.sgml
+++ b/doc/src/sgml/plperl.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/plperl.sgml,v 2.16 2002/03/06 19:05:57 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/plperl.sgml,v 2.17 2002/09/18 20:09:32 petere Exp $
 -->
 
  <chapter id="plperl">
@@ -14,154 +14,75 @@ $Header: /cvsroot/pgsql/doc/src/sgml/plperl.sgml,v 2.16 2002/03/06 19:05:57 momj
   </indexterm>
 
   <para>
-   PL/Perl is a loadable procedural language
-   that enables the <ulink url="http://www.perl.com">Perl</ulink> programming
-   language to be used to write 
-   <productname>PostgreSQL</productname> functions.
-  </para>
-
-  <!-- **** PL/Perl overview **** -->
-
-  <sect1 id="plperl-overview">
-   <title>Overview</title>
-
-   <para>
-    Normally, PL/Perl is installed as a <quote>trusted</> programming
-    language named <literal>plperl</>.  In this setup, certain Perl
-    operations are disabled to preserve security.  In general, the operations
-    that are restricted are those that interact with the environment. This
-    includes file handle operations, <literal>require</literal>, and
-    <literal>use</literal> (for external modules).
-    There is no way to access internals of the
-    database backend or to gain OS-level access under the permissions of the
-    <productname>PostgreSQL</productname> user ID, as a C function can do.
-    Thus, any unprivileged database user may be
-    permitted to use this language.
-   </para>
-   <para>
-    Sometimes it is desirable to write Perl functions that are not restricted
-    --- for example, one might want a Perl function that sends
-    mail.  To handle these cases, PL/Perl can also be installed as an
-    <quote>untrusted</> language (usually named <literal>plperlu</>).
-    In this case the full Perl language is available.  The writer of a PL/PerlU
-    function must take care that the function cannot be used to do anything
-    unwanted, since it will be able to do anything that could be done by
-    a user logged in as the database administrator.  Note that the database
-    system allows only database superusers to create functions in untrusted
-    languages.
-   </para>
- </sect1>
-
- <sect1 id="plperl-install">
-  <title>Building and Installing PL/Perl</title>
-
-  <para>
-   If the <option>--with-perl</option> option was supplied to the
-   <indexterm><primary><filename>configure</filename></primary></indexterm>
-   <filename>configure</filename> script,
-   the <productname>PostgreSQL</productname> build process will attempt to
-   build the PL/Perl shared library and install it in the 
-   <productname>PostgreSQL</productname> library directory.
+   PL/Perl is a loadable procedural language that enables you to write
+   <productname>PostgreSQL</productname> functions in the <ulink
+   url="http://www.perl.com">Perl</ulink> programming language.
   </para>
 
   <para>
-   On most platforms, since PL/Perl is a shared library, the
-   <indexterm><primary>libperl</primary></indexterm>
-   <filename>libperl</filename> library must be a shared library also.
-   At the time of this writing, this is almost never the case in prebuilt
-   Perl packages.  If this difficulty arises in your situation, a
-   message like this will appear during the build to point out this
-   fact:
-<screen>
-<computeroutput>
-*** Cannot build PL/Perl because libperl is not a shared library.
-*** You might have to rebuild your Perl installation.  Refer to
-*** the documentation for details.
-</computeroutput>
-</screen>
-   If you see this, you will have to re-build and install
-   <productname>Perl</productname> manually to be able to build
-   PL/Perl.  During the configuration process for
-   <productname>Perl</productname>, request a shared library.
+   To install PL/Perl in a particular database, use
+   <literal>createlang plperl <replaceable>dbname</></literal>.
   </para>
 
-  <para>
-   After having reinstalled Perl, change to the directory
-   <filename>src/pl/plperl</filename> in the
-   <productname>PostgreSQL</productname> source tree and issue the commands
-<programlisting>
-gmake clean
-gmake all
-gmake install
-</programlisting>
-   to complete the build and installation of the PL/Perl shared library.
-  </para>
-
-   <para>
-    To install
-    PL/Perl and/or PL/PerlU in a particular database, use the
-    <filename>createlang</filename> script, for example
-    <literal>createlang plperl <replaceable>dbname</></literal> or
-    <literal>createlang plperlu <replaceable>dbname</></literal>.
-   </para>
-
   <tip>
    <para>
     If a language is installed into <literal>template1</>, all subsequently
     created databases will have the language installed automatically.
    </para>
   </tip>
-  </sect1>
-
-  <!-- **** PL/Perl description **** -->
 
-  <sect1 id="plperl-description">
-   <title>Description</title>
-
-   <sect2>
-    <title>PL/Perl Functions and Arguments</title>
+  <note>
+   <para>
+    Users of source packages must specially enable the build of
+    PL/Perl during the installation process (refer to the installation
+    instructions for more information).  Users of binary packages
+    might find PL/Perl in a separate subpackage.
+   </para>
+  </note>
 
-    <para>
-     To create a function in the PL/Perl language, use the standard syntax
+ <sect1 id="plperl-funcs">
+  <title>PL/Perl Functions and Arguments</title>
 
-     <programlisting>
+  <para>
+   To create a function in the PL/Perl language, use the standard syntax:
+<programlisting>
 CREATE FUNCTION <replaceable>funcname</replaceable> (<replaceable>argument-types</replaceable>) RETURNS <replaceable>return-type</replaceable> AS '
     # PL/Perl function body
 ' LANGUAGE plperl;
-     </programlisting>
-
-     PL/PerlU is the same, except that the language should be specified as
-     <literal>plperlu</>.
-    </para>
+</programlisting>
+   The body of the function is ordinary Perl code.
+  </para>
 
-    <para>
-     The body of the function is ordinary Perl code.  Arguments and
-     results are handled as in any other Perl subroutine: arguments
-     are passed in <varname>@_</varname>, and a result value is returned
-     with <literal>return</> or as the last expression evaluated in the
-     function.  For example, a function
-     returning the greater of two integer values could be defined as:
+  <para>
+   Arguments and results are handled as in any other Perl subroutine:
+   Arguments are passed in <varname>@_</varname>, and a result value
+   is returned with <literal>return</> or as the last expression
+   evaluated in the function.  For example, a function returning the
+   greater of two integer values could be defined as:
 
-     <programlisting>
+<programlisting>
 CREATE FUNCTION perl_max (integer, integer) RETURNS integer AS '
     if ($_[0] > $_[1]) { return $_[0]; }
     return $_[1];
 ' LANGUAGE plperl;
-     </programlisting>
-
-     If a NULL is passed to a function, the argument value will appear
-     as <quote>undefined</> in Perl.  The above function definition will
-     not behave very nicely with NULL inputs (in fact, it will act as
-     though they are zeroes).  We could add <literal>WITH (isStrict)</>
-     to the function definition to make <productname>PostgreSQL</productname>
-     do something more reasonable: if a NULL is passed, the
-     function will not be called at all, but will just return a NULL
-     result automatically.  Alternatively, we could check for undefined
-     inputs in the function body.  For example, suppose that we wanted perl_max
-     with one null and one non-null argument to return the non-null
-     argument, rather than NULL:
-
-     <programlisting>
+</programlisting>
+  </para>
+
+  <para>
+   If an SQL null value is passed to a function, the argument value
+   will appear as <quote>undefined</> in Perl.  The above function
+   definition will not behave very nicely with null inputs (in fact,
+   it will act as though they are zeroes).  We could add
+   <literal>STRICT</> to the function definition to make
+   <productname>PostgreSQL</productname> do something more reasonable:
+   if a null value is passed, the function will not be called at all,
+   but will just return a null result automatically.  Alternatively,
+   we could check for undefined inputs in the function body.  For
+   example, suppose that we wanted <function>perl_max</function> with
+   one null and one non-null argument to return the non-null argument,
+   rather than a null value:
+
+<programlisting>
 CREATE FUNCTION perl_max (integer, integer) RETURNS integer AS '
     my ($a,$b) = @_;
     if (! defined $a) {
@@ -172,21 +93,21 @@ CREATE FUNCTION perl_max (integer, integer) RETURNS integer AS '
     if ($a > $b) { return $a; }
     return $b;
 ' LANGUAGE plperl;
-     </programlisting>
-    </para>
+</programlisting>
+  </para>
 
-    <para>
-     As shown above,
-     to return a NULL from a PL/Perl function, return an undefined
-     value.  This can be done whether the function is strict or not.
-    </para>
+  <para>
+   As shown above, to return an SQL null value from a PL/Perl
+   function, return an undefined value.  This can be done whether the
+   function is strict or not.
+  </para>
 
-    <para>
-     Composite-type arguments are passed to the function as references to
-     hashes.  The keys of the hash are the attribute names of the composite
-     type.  Here is an example:
+  <para>
+   Composite-type arguments are passed to the function as references
+   to hashes.  The keys of the hash are the attribute names of the
+   composite type.  Here is an example:
 
-     <programlisting>
+<programlisting>
 CREATE TABLE employee (
     name text,
     basesalary integer,
@@ -199,25 +120,97 @@ CREATE FUNCTION empcomp(employee) RETURNS integer AS '
 ' LANGUAGE plperl;
 
 SELECT name, empcomp(employee) FROM employee;
-     </programlisting>
-    </para>
+</programlisting>
+  </para>
 
-    <para>
-     There is not currently any support for returning a composite-type
-     result value.
-    </para>
+  <para>
+   There is currently no support for returning a composite-type result
+   value.
+  </para>
 
   <tip>
    <para>
     Because the function body is passed as an SQL string literal to
     <command>CREATE FUNCTION</command>, you have to escape single
-    quotes and backslashes within your Perl source, typically by doubling them
-    as shown in the above example.  Another possible approach is to
-    avoid writing single quotes by using Perl's extended quoting functions
-    (<literal>q[]</literal>, <literal>qq[]</literal>,
-    <literal>qw[]</literal>).
+    quotes and backslashes within your Perl source, typically by
+    doubling them as shown in the above example.  Another possible
+    approach is to avoid writing single quotes by using Perl's
+    extended quoting operators (<literal>q[]</literal>,
+    <literal>qq[]</literal>, <literal>qw[]</literal>).
    </para>
   </tip>
+ </sect1>
+
+ <sect1 id="plperl-data">
+  <title>Data Values in PL/Perl</title>
+
+  <para>
+   The argument values supplied to a PL/Perl function's script are
+   simply the input arguments converted to text form (just as if they
+   had been displayed by a <literal>SELECT</literal> statement).
+   Conversely, the <literal>return</> command will accept any string
+   that is acceptable input format for the function's declared return
+   type.  So, the PL/Perl programmer can manipulate data values as if
+   they were just text.
+  </para>
+ </sect1>
+
+ <sect1 id="plperl-database">
+  <title>Database Access from PL/Perl</title>
+
+  <para>
+   Access to the database itself from your Perl function can be done via
+   an experimental module <ulink
+   url="http://www.cpan.org/modules/by-module/DBD/APILOS/"><literal>DBD::PgSPI</literal></ulink>
+   (also available at <ulink url="http://www.cpan.org/SITES.html">CPAN
+   mirror sites</ulink>). This module makes available a
+   <acronym>DBI</>-compliant database-handle named
+   <varname>$pg_dbh</varname> that can be used to perform queries
+   with normal <acronym>DBI</> syntax.
+  </para>
+
+  <para>
+   PL/Perl itself presently provides only one additional Perl command:
+
+   <variablelist>
+    <varlistentry>
+     <indexterm>
+      <primary>elog</primary>
+      <secondary>PL/Perl</secondary>
+     </indexterm>
+
+     <term><function>elog</> <replaceable>level</replaceable>, <replaceable>msg</replaceable></term>
+     <listitem>
+      <para>
+       Emit a log or error message. Possible levels are
+       <literal>DEBUG</>, <literal>LOG</>, <literal>INFO</>,
+       <literal>NOTICE</>, <literal>WARNING</>, and <literal>ERROR</>.
+       <literal>ERROR</> raises an error condition: further execution
+       of the function is abandoned, and the current transaction is
+       aborted.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+ </sect1>
+
+ <sect1 id="plperl-trusted">
+  <title>Trusted and Untrusted PL/Perl</title>
+
+  <para>
+   Normally, PL/Perl is installed as a <quote>trusted</> programming
+   language named <literal>plperl</>.  In this setup, certain Perl
+   operations are disabled to preserve security.  In general, the
+   operations that are restricted are those that interact with the
+   environment. This includes file handle operations,
+   <literal>require</literal>, and <literal>use</literal> (for
+   external modules).  There is no way to access internals of the
+   database backend process or to gain OS-level access with the
+   permissions of the <productname>PostgreSQL</productname> user ID,
+   as a C function can do.  Thus, any unprivileged database user may
+   be permitted to use this language.
+  </para>
 
   <para>
    Here is an example of a function that will not work because file
@@ -231,89 +224,66 @@ CREATE FUNCTION badfunc() RETURNS integer AS '
 </programlisting>
    The creation of the function will succeed, but executing it will not.
   </para>
+
   <para>
-   Note that if the same function was created by a superuser using language 
-   <literal>plperlu</>, execution would succeed.
+   Sometimes it is desirable to write Perl functions that are not
+   restricted --- for example, one might want a Perl function that
+   sends mail.  To handle these cases, PL/Perl can also be installed
+   as an <quote>untrusted</> language (usually called
+   <quote>PL/PerlU</quote>).  In this case the full Perl language is
+   available.  If the <command>createlang</command> program is used to
+   install the language, the language name <literal>plperlu</literal>
+   will select the untrusted PL/Perl variant.
   </para>
 
-   </sect2>
-
-   <sect2>
-    <title>Data Values in PL/Perl</title>
-
-    <para>
-     The argument values supplied to a PL/Perl function's script are simply
-     the input arguments converted to text form (just as if they had been
-     displayed by a SELECT statement).  Conversely, the <literal>return</>
-     command will accept any string that is acceptable input format for
-     the function's declared return type.  So, the PL/Perl programmer can
-     manipulate data values as if they were just text.
-    </para>
+  <para>
+   The writer of a PL/PerlU function must take care that the function
+   cannot be used to do anything unwanted, since it will be able to do
+   anything that could be done by a user logged in as the database
+   administrator.  Note that the database system allows only database
+   superusers to create functions in untrusted languages.
+  </para>
 
-   </sect2>
+  <para>
+   If the above function was created by a superuser using the language
+   <literal>plperlu</>, execution would succeed.
+  </para>
+ </sect1>
 
-   <sect2>
-    <title>Database Access from PL/Perl</title>
+ <sect1 id="plperl-missing">
+  <title>Missing Features</title>
 
   <para>
-   Access to the database itself from your Perl function can be done via
-   an experimental module <ulink
-   url="http://www.cpan.org/modules/by-module/DBD/APILOS/"><literal>DBD::PgSPI</literal></ulink>
-   (also available at <ulink url="http://www.cpan.org/SITES.html">CPAN
-   mirror sites</ulink>). This module makes available a
-   <acronym>DBI</>-compliant database-handle named
-   <varname>$pg_dbh</varname> that can be used to perform queries
-   with normal <acronym>DBI</> syntax.
+   The following features are currently missing from PL/Perl, but they
+   would make welcome contributions:
+
+   <itemizedlist>
+    <listitem>
+     <para>
+      PL/Perl functions cannot call each other directly (because they
+      are anonymous subroutines inside Perl).  There's presently no
+      way for them to share global variables, either.
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      PL/Perl cannot be used to write trigger functions.
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      <application>DBD::PgSPI</applicatioN> or similar capability
+      should be integrated into the standard
+      <productname>PostgreSQL</productname> distribution.
+     </para>
+    </listitem>
+   </itemizedlist>
   </para>
+ </sect1>
 
-    <para>
-     PL/Perl itself presently provides only one additional Perl command:
-    </para>
-
-    <variablelist>
-     <varlistentry>
-      <indexterm>
-       <primary>elog</primary>
-      </indexterm>
-      <term><function>elog</> <replaceable>level</replaceable>, <replaceable>msg</replaceable></term>
-      <listitem>
-       <para>
-	Emit a log or error message. Possible levels are
-	<literal>DEBUG</>, <literal>LOG</>, <literal>INFO</>,
-	<literal>NOTICE</>, <literal>WARNING</>, and <literal>ERROR</>.
-	<literal>ERROR</> raises an error condition: further execution
-	of the function is abandoned, and the current transaction is
-	aborted.
-       </para>
-      </listitem>
-     </varlistentry>
-
-    </variablelist>
-
-   </sect2>
-
-   <sect2>
-    <title>Missing Features</title>
-
-    <para>
-     PL/Perl functions cannot call each other directly (because they
-     are anonymous subroutines inside Perl).  There's presently
-     no way for them to share global variables, either.
-    </para>
-
-    <para>
-     PL/Perl cannot currently be used to write trigger functions.
-    </para>
-
-    <para>
-     DBD::PgSPI or similar capability should be integrated
-     into the standard <productname>PostgreSQL</productname> distribution.
-    </para>
-
-   </sect2>
-
-  </sect1>
- </chapter>
+</chapter>
 
 <!-- Keep this comment at the end of the file
 Local variables:
diff --git a/doc/src/sgml/plpython.sgml b/doc/src/sgml/plpython.sgml
index 2e38a5c7917..110c2a826e5 100644
--- a/doc/src/sgml/plpython.sgml
+++ b/doc/src/sgml/plpython.sgml
@@ -1,4 +1,4 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/plpython.sgml,v 1.10 2002/03/22 19:20:18 petere Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/plpython.sgml,v 1.11 2002/09/18 20:09:32 petere Exp $ -->
 
 <chapter id="plpython">
  <title>PL/Python - Python Procedural Language</title>
@@ -6,90 +6,42 @@
  <indexterm zone="plpython"><primary>PL/Python</></>
  <indexterm zone="plpython"><primary>Python</></>
 
- <sect1 id="plpython-intro">
-  <title>Introduction</title>
+ <para>
+  The <application>PL/Python</application> procedural language allows
+  <productname>PostgreSQL</productname> functions to be written in the
+  <ulink url="http://www.python.org">Python</ulink> language.
+ </para>
 
-  <para>
-   The <application>PL/Python</application> procedural language allows
-   <productname>PostgreSQL</productname> functions to be written in
-   the <ulink url="http://www.python.org">Python</ulink> language.
-  </para>
+ <para>
+  To install PL/Python in a particular database, use
+  <literal>createlang plpython <replaceable>dbname</></literal>.
+ </para>
 
+ <note>
   <para>
-   The current version of <application>PL/Python</application>
-   functions as a trusted language only; access to the file system and
-   other local resources is disabled.  Specifically,
-   <application>PL/Python</application> uses the Python restricted
-   execution environment, further restricts it to prevent the use of
-   the file <function>open</> call, and allows only modules from a
-   specific list to be imported.  Presently, that list includes:
-   array, bisect, binascii, calendar, cmath, codecs, errno, marshal,
-   math, md5, mpz, operator, pcre, pickle, random, re, regex, sre,
-   sha, string, StringIO, struct, time, whrandom, and zlib.
+   Users of source packages must specially enable the build of
+   PL/Python during the installation process (refer to the
+   installation instructions for more information).  Users of binary
+   packages might find PL/Python in a separate subpackage.
   </para>
+ </note>
 
-  <para>
-   In the current version, any database error encountered while
-   running a <application>PL/Python</application> function will result
-   in the immediate termination of that function by the server.  It is
-   not possible to trap error conditions using Python <literal>try
-   ... catch</literal> constructs.  For example, a syntax error in an
-   SQL statement passed to the <literal>plpy.execute()</literal> call
-   will terminate the function.  This behavior may be changed in a
-   future release.
-  </para>
- </sect1>
-
- <sect1 id="plpython-install">
-  <title>Installation</title>
-
-  <para>
-   To build PL/Python, the <option>--with-python</option> option needs
-   to be specified when running <filename>configure</filename>.  If
-   after building and installing you have a file called
-   <filename>plpython.so</filename> (possibly a different extension),
-   then everything went well.  Otherwise you should have seen a notice
-   like this flying by:
-<screen>
-*** Cannot build PL/Python because libpython is not a shared library.
-*** You might have to rebuild your Python installation.  Refer to
-*** the documentation for details.
-</screen>
-   That means you have to rebuild (part of) your Python installation
-   to supply this shared library.
-  </para>
-
-  <para>
-   The catch is that the Python distribution or the Python maintainers
-   do not provide any direct way to do this.  The closest thing we can
-   offer you is the information in <ulink
-   url="http://www.python.org/doc/FAQ.html#3.30">Python FAQ
-   3.30</ulink>.  On some operating systems you don't really have to
-   build a shared library, but then you will have to convince the
-   PostgreSQL build system of this.  Consult the
-   <filename>Makefile</filename> in the
-   <filename>src/pl/plpython</filename> directory for details.
-  </para>
- </sect1>
-
- <sect1 id="plpython-using">
-  <title>Using PL/Python</title>
+ <sect1 id="plpython-funcs">
+  <title>PL/Python Functions</title>
 
   <para>
-   There are sample functions in
-   <filename>plpython_function.sql</filename>.  The Python code you
-   write gets transformed into a function.  E.g.,
+   The Python code you write gets transformed into a function.  E.g.,
 <programlisting>
-CREATE FUNCTION myfunc(text) RETURNS text AS
-'return args[0]'
-LANGUAGE 'plpython';
+CREATE FUNCTION myfunc(text) RETURNS text
+    AS 'return args[0]'
+    LANGUAGE 'plpython';
 </programlisting>
 
    gets transformed into
 
 <programlisting>
 def __plpython_procedure_myfunc_23456():
-	return args[0]
+        return args[0]
 </programlisting>
 
    where 23456 is the OID of the function.
@@ -98,51 +50,68 @@ def __plpython_procedure_myfunc_23456():
   <para>
    If you do not provide a return value, Python returns the default
    <symbol>None</symbol> which may or may not be what you want.  The
-   language module translates Python's None into SQL NULL.
+   language module translates Python's <symbol>None</symbol> into the
+   SQL null value.
   </para>
 
   <para>
-   <productname>PostgreSQL</> function variables are available in the global
-   <varname>args</varname> list.  In the <function>myfunc</function>
-   example, <varname>args[0]</> contains whatever was passed in as the text
-   argument.  For <literal>myfunc2(text, integer)</literal>, <varname>args[0]</>
-   would contain the <type>text</type> variable and <varname>args[1]</varname> the <type>integer</type> variable.
+   The <productname>PostgreSQL</> function parameters are available in
+   the global <varname>args</varname> list.  In the
+   <function>myfunc</function> example, <varname>args[0]</> contains
+   whatever was passed in as the text argument.  For
+   <literal>myfunc2(text, integer)</literal>, <varname>args[0]</>
+   would contain the <type>text</type> variable and
+   <varname>args[1]</varname> the <type>integer</type> variable.
   </para>
 
   <para>
-   The global dictionary SD is available to store data between
-   function calls.  This variable is private static data.  The global
-   dictionary GD is public data, available to all python functions
-   within a backend.  Use with care.
+   The global dictionary <varname>SD</varname> is available to store
+   data between function calls.  This variable is private static data.
+   The global dictionary <varname>GD</varname> is public data,
+   available to all Python functions within a session.  Use with care.
   </para>
 
   <para>
    Each function gets its own restricted execution object in the
    Python interpreter, so that global data and function arguments from
    <function>myfunc</function> are not available to
-   <function>myfunc2</function>.  The exception is the data in the GD
-   dictionary, as mentioned above.
+   <function>myfunc2</function>.  The exception is the data in the
+   <varname>GD</varname> dictionary, as mentioned above.
   </para>
+ </sect1>
+
+ <sect1 id="plpython-trigger">
+  <title>Trigger Functions</title>
 
   <para>
-   When a function is used in a trigger, the dictionary TD contains
-   transaction related values.  The trigger tuples are in <literal>TD["new"]</>
-   and/or <literal>TD["old"]</> depending on the trigger event.  <literal>TD["event"]</>
-   contains the event as a string (<literal>INSERT</>, <literal>UPDATE</>, <literal>DELETE</>, or
-   <literal>UNKNOWN</>).  TD["when"] contains one of (<literal>BEFORE</>, <literal>AFTER</>, or
-   <literal>UNKNOWN</>).  <literal>TD["level"]</> contains one of <literal>ROW</>, <literal>STATEMENT</>, or
-   <literal>UNKNOWN</>.  <literal>TD["name"]</> contains the trigger name, and <literal>TD["relid"]</>
-   contains the relation id of the table on which the trigger occurred.
-   If the trigger was called with arguments they are available
-   in <literal>TD["args"][0]</> to <literal>TD["args"][(n -1)]</>.
+   When a function is used in a trigger, the dictionary
+   <literal>TD</literal> contains trigger-related values.  The trigger
+   rows are in <literal>TD["new"]</> and/or <literal>TD["old"]</>
+   depending on the trigger event.  <literal>TD["event"]</> contains
+   the event as a string (<literal>INSERT</>, <literal>UPDATE</>,
+   <literal>DELETE</>, or <literal>UNKNOWN</>).
+   <literal>TD["when"]</> contains one of <literal>BEFORE</>,
+   <literal>AFTER</>, and <literal>UNKNOWN</>.
+   <literal>TD["level"]</> contains one of <literal>ROW</>,
+   <literal>STATEMENT</>, and <literal>UNKNOWN</>.
+   <literal>TD["name"]</> contains the trigger name, and
+   <literal>TD["relid"]</> contains the relation ID of the table on
+   which the trigger occurred.  If the trigger was called with
+   arguments they are available in <literal>TD["args"][0]</> to
+   <literal>TD["args"][(n-1)]</>.
   </para>
 
   <para>
-   If the trigger <quote>when</quote> is <literal>BEFORE</>, you may return <literal>None</literal> or <literal>"OK"</literal>
-   from the Python function to indicate the tuple is unmodified,
-   <literal>"SKIP"</> to abort the event, or <literal>"MODIFIED"</> to indicate you've
-   modified the tuple.
+   If the <literal>TD["when"]</literal> is <literal>BEFORE</>, you may
+   return <literal>None</literal> or <literal>"OK"</literal> from the
+   Python function to indicate the row is unmodified,
+   <literal>"SKIP"</> to abort the event, or <literal>"MODIFIED"</> to
+   indicate you've modified the row.
   </para>
+ </sect1>
+
+ <sect1 id="plpython-database">
+  <title>Database Access</title>
 
   <para>
    The PL/Python language module automatically imports a Python module
@@ -150,54 +119,64 @@ def __plpython_procedure_myfunc_23456():
    this module are available to you in the Python code as
    <literal>plpy.<replaceable>foo</replaceable></literal>.  At present
    <literal>plpy</literal> implements the functions
-   <literal>plpy.debug("msg")</literal>, 
+   <literal>plpy.debug("msg")</literal>,
    <literal>plpy.log("msg")</literal>,
    <literal>plpy.info("msg")</literal>,
    <literal>plpy.notice("msg")</literal>,
    <literal>plpy.warning("msg")</literal>,
    <literal>plpy.error("msg")</literal>, and
    <literal>plpy.fatal("msg")</literal>.  They are mostly equivalent
-   to calling <literal>elog(<replaceable>LEVEL</>, "msg")</literal>.
-   <function>plpy.error</function> and <function>plpy.fatal</function>
-   actually raise a Python exception which, if uncaught, causes the
-   PL/Python module to call <literal>elog(ERROR, msg)</literal> when
-   the function handler returns from the Python interpreter.  Long
-   jumping out of the Python interpreter is probably not good.
-   <literal>raise plpy.ERROR("msg")</literal> and <literal>raise
+   to calling <literal>elog(<replaceable>LEVEL</>, "msg")</literal>
+   from C code.  <function>plpy.error</function> and
+   <function>plpy.fatal</function> actually raise a Python exception
+   which, if uncaught, causes the PL/Python module to call
+   <literal>elog(ERROR, msg)</literal> when the function handler
+   returns from the Python interpreter.  Long-jumping out of the
+   Python interpreter is probably not good.  <literal>raise
+   plpy.ERROR("msg")</literal> and <literal>raise
    plpy.FATAL("msg")</literal> are equivalent to calling
-   <function>plpy.error</function> or <function>plpy.fatal</function>.
+   <function>plpy.error</function> and
+   <function>plpy.fatal</function>, respectively.
   </para>
 
   <para>
-   Additionally, the <literal>plpy</literal> module provides two functions called
-   <function>execute</function> and <function>prepare</function>.
-   Calling <function>plpy.execute</function> with a query string, and
-   an optional limit argument, causes that query to be run, and the
-   result returned in a result object.  The result object emulates a
+   Additionally, the <literal>plpy</literal> module provides two
+   functions called <function>execute</function> and
+   <function>prepare</function>.  Calling
+   <function>plpy.execute</function> with a query string and an
+   optional limit argument causes that query to be run and the result
+   to be returned in a result object.  The result object emulates a
    list or dictionary object.  The result object can be accessed by
-   row number, and field name.  It has these additional methods:
+   row number and field name.  It has these additional methods:
    <function>nrows()</function> which returns the number of rows
    returned by the query, and <function>status</function> which is the
    <function>SPI_exec</function> return variable.  The result object
    can be modified.
+  </para>
 
+  <para>
+   For example,
 <programlisting>
 rv = plpy.execute("SELECT * FROM my_table", 5)
 </programlisting>
-   returns up to 5 rows from my_table.  Ff my_table has a column
-   my_field it would be accessed as
+   returns up to 5 rows from <literal>my_table</literal>.  If
+   <literal>my_table</literal> has a column
+   <literal>my_field</literal>, it would be accessed as
 <programlisting>
 foo = rv[i]["my_field"]
 </programlisting>
+  </para>
+
+  <para>
    The second function <function>plpy.prepare</function> is called
-   with a query string, and a list of argument types if you have bind
-   variables in the query.
+   with a query string and a list of argument types if you have bind
+   variables in the query.  For example:
 <programlisting>
 plan = plpy.prepare("SELECT last_name FROM my_users WHERE first_name = $1", [ "text" ])
 </programlisting>
-   text is the type of the variable you will be passing as $1.  After
-   preparing you use the function <function>plpy.execute</function> to
-   run it.
+   <literal>text</literal> is the type of the variable you will be
+   passing as <literal>$1</literal>.  After preparing a statement, you
+   use the function <function>plpy.execute</function> to run it:
 <programlisting>
 rv = plpy.execute(plan, [ "name" ], 5)
 </programlisting>
@@ -206,6 +185,17 @@ rv = plpy.execute(plan, [ "name" ], 5)
   </para>
 
   <para>
+   In the current version, any database error encountered while
+   running a <application>PL/Python</application> function will result
+   in the immediate termination of that function by the server; it is
+   not possible to trap error conditions using Python <literal>try
+   ... catch</literal> constructs.  For example, a syntax error in an
+   SQL statement passed to the <literal>plpy.execute()</literal> call
+   will terminate the function.  This behavior may be changed in a
+   future release.
+  </para>
+
+  <para>
    When you prepare a plan using the PL/Python module it is
    automatically saved.  Read the SPI documentation (<xref
    linkend="spi">) for a description of what this means.  The take
@@ -220,4 +210,21 @@ plan = plpy.prepare("SOME OTHER QUERY")
   </para>
  </sect1>
 
+ <sect1 id="plpython-trusted">
+  <title>Restricted Environment</title>
+
+  <para>
+   The current version of <application>PL/Python</application>
+   functions as a trusted language only; access to the file system and
+   other local resources is disabled.  Specifically,
+   <application>PL/Python</application> uses the Python restricted
+   execution environment, further restricts it to prevent the use of
+   the file <function>open</> call, and allows only modules from a
+   specific list to be imported.  Presently, that list includes:
+   array, bisect, binascii, calendar, cmath, codecs, errno, marshal,
+   math, md5, mpz, operator, pcre, pickle, random, re, regex, sre,
+   sha, string, StringIO, struct, time, whrandom, and zlib.
+  </para>
+ </sect1>
+
 </chapter>
diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index 3bded5cf93b..c4a605683b9 100644
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.74 2002/08/27 20:16:48 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.75 2002/09/18 20:09:32 petere Exp $
 PostgreSQL documentation
 -->
 
@@ -2274,33 +2274,6 @@ $endif
     <application>readline</application> feature. Read its documentation
     for further details.)
     </para>
-
-    <para>
-    If you have the readline library installed but
-    <application>psql</application> does not seem to use it, you must
-    make sure that <productname>PostgreSQL</productname>'s top-level
-    <filename>configure</filename> script finds it.
-    <filename>configure</filename> needs to find both the library
-    <filename>libreadline.a</filename> (or a shared library equivalent)
-    <emphasis>and</emphasis> the header files
-    <filename>readline.h</filename> and <filename>history.h</filename>
-    (or <filename>readline/readline.h</filename> and
-    <filename>readline/history.h</filename>) in appropriate directories.
-    If you have the library and header files installed in an obscure
-    place you must tell <filename>configure</filename> about them, for
-    example:
-<programlisting>
-$ ./configure --with-includes=/opt/gnu/include --with-libs=/opt/gnu/lib  ...
-</programlisting>
-    Then you have to recompile <application>psql</application> (not
-    necessarily the entire code tree).
-    </para>
-
-    <para>
-    The <acronym>GNU</acronym> readline library can be obtained from the
-    <acronym>GNU</acronym> project's <acronym>FTP</acronym> server at
-    <ulink URL="ftp://ftp.gnu.org">ftp://ftp.gnu.org</ulink>.
-    </para>
    </refsect3>
   </refsect2>
  </refsect1>
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index b993323db61..3ae2750fd0c 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.136 2002/09/17 21:41:47 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.137 2002/09/18 20:09:32 petere Exp $
 -->
 
 <Chapter Id="runtime">
@@ -973,8 +973,8 @@ env PGOPTIONS='-c geqo=off' psql
         to turn this on, as it might expose programming mistakes. To use
         this option, the macro <literal>USE_ASSERT_CHECKING</literal>
         must be defined when <productname>PostgreSQL</productname> is
-        built (see the configure option
-        <literal>--enable-cassert</literal>). Note that
+        built (accomplished by the configure option
+        <option>--enable-cassert</option>). Note that
         <literal>DEBUG_ASSERTIONS</literal> defaults to on if
         <productname>PostgreSQL</productname> has been built with
 	assertions enabled.
@@ -1176,11 +1176,6 @@ env PGOPTIONS='-c geqo=off' psql
         <systemitem>syslog</> is off. This option must be set at server
         start.
        </para>
-       <para>
-        To use <systemitem>syslog</>, the build of
-        <productname>PostgreSQL</productname> must be configured with
-        the <option>--enable-syslog</option> option.
-       </para>
       </listitem>
      </varlistentry>