General editing

a8cb3368 · Peter Eisentraut · cb1d036a · a8cb3368 · a8cb3368 · a8cb3368
8 changed file
--- a/doc/src/sgml/datetime.sgml
+++ b/doc/src/sgml/datetime.sgml
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/datetime.sgml,v 2.30 2003/03/13 01:30:27 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/datetime.sgml,v 2.31 2003/04/07 01:29:25 petere Exp $
 -->

 <appendix id="datetime-appendix">
@@ -210,7 +210,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/datetime.sgml,v 2.30 2003/03/13 01:30:27 pe
  </sect1>


-  <sect1>
+  <sect1 id="datetime-keywords">
   <title>Date/Time Key Words</title>

   <para>

--- a/doc/src/sgml/jdbc.sgml
+++ b/doc/src/sgml/jdbc.sgml
--- a/doc/src/sgml/plperl.sgml
+++ b/doc/src/sgml/plperl.sgml
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/plperl.sgml,v 2.18 2002/09/21 18:32:53 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/plperl.sgml,v 2.19 2003/04/07 01:29:25 petere Exp $
 -->

 <chapter id="plperl">
@@ -34,8 +34,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/plperl.sgml,v 2.18 2002/09/21 18:32:53 pete
  <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
+    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>
@@ -57,8 +57,12 @@ CREATE FUNCTION <replaceable>funcname</replaceable> (<replaceable>argument-types
   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:
+   evaluated in the function.
+  </para>
+
+  <para>
+   For example, a function returning the greater of two integer values
+   could be defined as:

 <programlisting>
 CREATE FUNCTION perl_max (integer, integer) RETURNS integer AS '
@@ -145,7 +149,7 @@ SELECT name, empcomp(employee) FROM employee;
  <title>Data Values in PL/Perl</title>

  <para>
-   The argument values supplied to a PL/Perl function's script are
+   The argument values supplied to a PL/Perl function's code 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
@@ -206,8 +210,8 @@ SELECT name, empcomp(employee) FROM employee;
   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,
+   database server process or to gain OS-level access with the
+   permissions of the server process,
   as a C function can do.  Thus, any unprivileged database user may
   be permitted to use this language.
  </para>
@@ -227,7 +231,7 @@ CREATE FUNCTION badfunc() RETURNS integer AS '

  <para>
   Sometimes it is desirable to write Perl functions that are not
-   restricted --- for example, one might want a Perl function that
+   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
   <application>PL/PerlU</application>).  In this case the full Perl language is
@@ -255,7 +259,7 @@ CREATE FUNCTION badfunc() RETURNS integer AS '

  <para>
   The following features are currently missing from PL/Perl, but they
-   would make welcome contributions:
+   would make welcome contributions.

   <itemizedlist>
    <listitem>

--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
--- a/doc/src/sgml/plpython.sgml
+++ b/doc/src/sgml/plpython.sgml
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/plpython.sgml,v 1.15 2002/10/21 20:34:09 momjian Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/plpython.sgml,v 1.16 2003/04/07 01:29:25 petere Exp $ -->

 <chapter id="plpython">
 <title>PL/Python - Python Procedural Language</title>
@@ -17,11 +17,18 @@
  <literal>createlang plpython <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>
+
 <note>
  <para>
   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
+   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>
@@ -30,11 +37,11 @@
  <title>PL/Python Functions</title>

  <para>
-   The Python code you write gets transformed into a function.  E.g.,
+   The Python code you write gets transformed into a Python function.  E.g.,
 <programlisting>
 CREATE FUNCTION myfunc(text) RETURNS text
    AS 'return args[0]'
-    LANGUAGE 'plpython';
+    LANGUAGE plpython;
 </programlisting>

   gets transformed into
@@ -49,7 +56,7 @@ 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
+   <symbol>None</symbol>. The
   language module translates Python's <symbol>None</symbol> into the
   SQL null value.
  </para>
@@ -60,8 +67,8 @@ def __plpython_procedure_myfunc_23456():
   <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.
+   would contain the <type>text</type> argument and
+   <varname>args[1]</varname> the <type>integer</type> argument.
  </para>

  <para>
@@ -95,14 +102,14 @@ def __plpython_procedure_myfunc_23456():
   <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
+   <literal>TD["relid"]</> contains the OID 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 <literal>TD["when"]</literal> is <literal>BEFORE</>, you may
+   If <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>"MODIFY"</> to
@@ -147,10 +154,10 @@ def __plpython_procedure_myfunc_23456():
   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:
-   <function>nrows()</function> which returns the number of rows
+   row number and column 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
+   <function>SPI_exec()</function> return value.  The result object
   can be modified.
  </para>

@@ -161,27 +168,27 @@ rv = plpy.execute("SELECT * FROM my_table", 5)
 </programlisting>
   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
+   <literal>my_column</literal>, it would be accessed as
 <programlisting>
-foo = rv[i]["my_field"]
+foo = rv[i]["my_column"]
 </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.  For example:
+   The second function, <function>plpy.prepare</function>, prepares the
+   execution plan for a query.  It is called with a query string and a
+   list of parameter types, if you have parameter references in the
+   query.  For example:
 <programlisting>
 plan = plpy.prepare("SELECT last_name FROM my_users WHERE first_name = $1", [ "text" ])
 </programlisting>
   <literal>text</literal> is the type of the variable you will be
-   passing as <literal>$1</literal>.  After preparing a statement, you
+   passing for <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>
-   The limit argument is optional in the call to
-   <function>plpy.execute</function>.
+   The third argument is the limit and is optional.
  </para>

  <para>
@@ -190,7 +197,7 @@ rv = plpy.execute(plan, [ "name" ], 5)
   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
+   SQL statement passed to the <literal>plpy.execute</literal> call
   will terminate the function.  This behavior may be changed in a
   future release.
  </para>
@@ -199,22 +206,19 @@ rv = plpy.execute(plan, [ "name" ], 5)
   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.
-  </para>
-
-  <para>
   In order to make effective use of this across function calls
   one needs to use one of the persistent storage dictionaries
-   <literal>SD</literal> or <literal>GD</literal>, see
-   <xref linkend="plpython-funcs">. For example:
+   <literal>SD</literal> or <literal>GD</literal> (see
+   <xref linkend="plpython-funcs">). For example:
 <programlisting>
-CREATE FUNCTION usesavedplan ( ) RETURNS TRIGGER AS '
-   if SD.has_key("plan"):
-      plan = SD["plan"]
-   else:
-      plan = plpy.prepare("SELECT 1")
-      SD["plan"] = plan
-   # rest of function
-' LANGUAGE 'plpython';
+CREATE FUNCTION usesavedplan() RETURNS trigger AS '
+    if SD.has_key("plan"):
+        plan = SD["plan"]
+    else:
+        plan = plpy.prepare("SELECT 1")
+        SD["plan"] = plan
+    # rest of function
+' LANGUAGE plpython;
 </programlisting>
  </para>
 </sect1>

--- a/doc/src/sgml/pltcl.sgml
+++ b/doc/src/sgml/pltcl.sgml
--- a/doc/src/sgml/pygresql.sgml
+++ b/doc/src/sgml/pygresql.sgml
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/Attic/pygresql.sgml,v 1.9 2002/12/12 22:49:27 momjian Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/Attic/pygresql.sgml,v 1.10 2003/04/07 01:29:25 petere Exp $ -->

 <chapter id="pygresql">
 <title><application>PyGreSQL</application> - <application>Python</application> Interface</title>
@@ -334,13 +334,10 @@ make && make install
  <acronym>API</acronym> at <ulink
  url="http://www.python.org/topics/database/DatabaseAPI-2.0.html"
  >http://www.python.org/topics/database/DatabaseAPI-2.0.html</ulink>.
- </para>
-
- <para>
  A tutorial-like introduction to the <acronym>DB-API</acronym> can be
  found at <ulink
  url="http://www2.linuxjournal.com/lj-issues/issue49/2605.html"
-  >http://www2.linuxjournal.com/lj-issues/issue49/2605.html</ulink>
+  >http://www2.linuxjournal.com/lj-issues/issue49/2605.html</ulink>.
 </para>

 <sect1 id="pygresql-pg">
@@ -365,16 +362,15 @@ make && make install

    <listitem>
     <para>
-      <classname>pgqueryobject</classname> that handles query results.
+      <classname>pgqueryobject</classname>, which handles query results.
     </para>
    </listitem>
   </itemizedlist>
  </para>

  <para>
-   If you want to see a simple example of the use of some of these
-   functions, see <ulink url="http://www.druid.net/rides"
-   >http://www.druid.net/rides</ulink> where you can find a link at the
+   If you want to see a simple example of the use this module,
+   see <ulink url="http://www.druid.net/rides"></ulink> where you can find a link at the
   bottom to the actual <application>Python</application> code for the
   page.
  </para>
@@ -395,9 +391,9 @@ make && make install
      <term><varname>INV_WRITE</varname></term>
      <listitem>
       <para>
-        large objects access modes, used by
+        Large objects access modes, used by
        <function>(pgobject.)locreate</function> and
-        <function>(pglarge.)open</function>.
+        <function>(pglarge.)open</function>
       </para>
      </listitem>
     </varlistentry>
@@ -408,7 +404,7 @@ make && make install
      <term><varname>SEEK_END</varname></term>
      <listitem>
       <para>
-        positional flags, used by <function>(pglarge.)seek</function>.
+        Positional flags, used by <function>(pglarge.)seek</function>
       </para>
      </listitem>
     </varlistentry>
@@ -418,7 +414,7 @@ make && make install
      <term><varname>__version__</varname></term>
      <listitem>
       <para>
-        constants that give the current version
+        Constants that give the current version
       </para>
      </listitem>
     </varlistentry>
@@ -443,13 +439,13 @@ make && make install
   to handle general connection parameters without heavy code in your
   programs. You can prompt the user for a value, put it in the
   default variable, and forget it, without having to modify your
-   environment. The support for default variables can be disabled by
+   environment. The support for default variables can be disabled at build time by
   setting the <option>-DNO_DEF_VAR</option> option in the Python
   <filename>Setup</> file. Methods relative to this are specified by the tag [DV].
  </para>

  <para>
-   All variables are set to <symbol>None</symbol> at module
+   All default values are set to <symbol>None</symbol> at module
   initialization, specifying that standard environment variables
   should be used.
  </para>
@@ -478,7 +474,7 @@ connect(<optional><parameter>dbname</parameter></optional>, <optional><parameter
       <term><parameter>dbname</parameter></term>

       <listitem>
-        <para>Name of connected database (string/<symbol>None</>).</para>
+        <para>Name of connected database (string/<symbol>None</>)</para>
       </listitem>
      </varlistentry>

@@ -486,7 +482,7 @@ connect(<optional><parameter>dbname</parameter></optional>, <optional><parameter
       <term><parameter>host</parameter></term>

       <listitem>
-        <para>Name of the server host (string/<symbol>None</>).</para>
+        <para>Name of the server host (string/<symbol>None</>)</para>
       </listitem>
      </varlistentry>

@@ -494,7 +490,7 @@ connect(<optional><parameter>dbname</parameter></optional>, <optional><parameter
       <term><parameter>port</parameter></term>

       <listitem>
-        <para>Port used by the database server (integer/-1).</para>
+        <para>Port used by the database server (integer/-1)</para>
       </listitem>
      </varlistentry>

@@ -503,7 +499,7 @@ connect(<optional><parameter>dbname</parameter></optional>, <optional><parameter

       <listitem>
        <para>
-         Options for the server (string/<symbol>None</>).
+         Options for the server (string/<symbol>None</>)
        </para>
       </listitem>
      </varlistentry>
@@ -513,8 +509,8 @@ connect(<optional><parameter>dbname</parameter></optional>, <optional><parameter

       <listitem>
        <para>
-         File or tty for optional debug output from backend
-         (string/<symbol>None</>).
+         File or TTY for optional debug output from server
+         (string/<symbol>None</>)
        </para>
       </listitem>
      </varlistentry>
@@ -524,7 +520,7 @@ connect(<optional><parameter>dbname</parameter></optional>, <optional><parameter

       <listitem>
        <para>
-         <productname>PostgreSQL</productname> user (string/<symbol>None</>).
+         <productname>PostgreSQL</productname> user (string/<symbol>None</>)
        </para>
       </listitem>
      </varlistentry>
@@ -533,7 +529,7 @@ connect(<optional><parameter>dbname</parameter></optional>, <optional><parameter
       <term><parameter>passwd</parameter></term>

       <listitem>
-        <para>Password for user (string/<symbol>None</>).</para>
+        <para>Password for user (string/<symbol>None</>)</para>
       </listitem>
      </varlistentry>
     </variablelist>
@@ -601,12 +597,11 @@ connect(<optional><parameter>dbname</parameter></optional>, <optional><parameter

    <para>
     This method opens a connection to a specified database on a given
-     <productname>PostgreSQL</productname> server. You can use
-     key words here, as described in the
-     <application>Python</application> tutorial.  The names of the
+     <productname>PostgreSQL</productname> server. The arguments can be
+     given using key words here.  The names of the
     key words are the name of the parameters given in the syntax
     line. For a precise description of the parameters, please refer
-     to the <productname>PostgreSQL</productname> user manual.
+     to <xref linkend="libpq">.
    </para>
   </refsect1>
      

--- a/doc/src/sgml/xplang.sgml
+++ b/doc/src/sgml/xplang.sgml
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/xplang.sgml,v 1.20 2003/01/31 00:10:51 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/xplang.sgml,v 1.21 2003/04/07 01:29:26 petere Exp $
 -->

 <chapter id="xplang">
  <title id="xplang-title">Procedural Languages</title>

-  <sect1 id="xplang-intro">
-   <title>Introduction</title>
-
  <para>
   <productname>PostgreSQL</productname> allows users to add new
   programming languages to be available for writing functions and
@@ -21,7 +18,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/xplang.sgml,v 1.20 2003/01/31 00:10:51 tgl
   could serve as <quote>glue</quote> between
   <productname>PostgreSQL</productname> and an existing implementation
   of a programming language.  The handler itself is a special
-   programming language function compiled into a shared object and
+   C language function compiled into a shared object and
   loaded on demand.
  </para>

@@ -31,7 +28,6 @@ $Header: /cvsroot/pgsql/doc/src/sgml/xplang.sgml,v 1.20 2003/01/31 00:10:51 tgl
   available in the standard <productname>PostgreSQL</productname>
   distribution, which can serve as examples.
  </para>
-  </sect1>

  <sect1 id="xplang-install">
   <title>Installing Procedural Languages</title>
@@ -39,22 +35,24 @@ $Header: /cvsroot/pgsql/doc/src/sgml/xplang.sgml,v 1.20 2003/01/31 00:10:51 tgl
   <para>
    A procedural language must be <quote>installed</quote> into each
    database where it is to be used.  But procedural languages installed in
-    the template1 database are automatically available in all
+    the database <literal>template1</> are automatically available in all
    subsequently created databases. So the database administrator can
-    decide which languages are available in which databases, and can make
+    decide which languages are available in which databases and can make
    some languages available by default if he chooses.
   </para>

   <para>
    For the languages supplied with the standard distribution, the
-    shell script <filename>createlang</filename> may be used instead
-    of carrying out the details by hand.  For example, to install <application>PL/pgSQL</application>
-    into the template1 database, use
+    program <command>createlang</command> may be used to install the
+    language instead of carrying out the details by hand.  For
+    example, to install the language
+    <application>PL/pgSQL</application> into the database
+    <literal>template1</>, use
 <programlisting>
 createlang plpgsql template1
 </programlisting>
    The manual procedure described below is only recommended for
-    installing custom languages that <filename>createlang</filename>
+    installing custom languages that <command>createlang</command>
    does not know about.
   </para>

@@ -64,8 +62,11 @@ createlang plpgsql template1
    </title>

    <para>
-     A procedural language is installed in the database in three
-     steps, which must be carried out by a database superuser.
+     A procedural language is installed in a database in three steps,
+     which must be carried out by a database superuser.  The
+     <command>createlang</command> programm automates <xref
+     linkend="xplang-install-cr1"> and <xref
+     linkend="xplang-install-cr2">.
    </para>

    <step performance="required">
@@ -81,12 +82,13 @@ createlang plpgsql template1
     <para>
      The handler must be declared with the command
 <synopsis>
-CREATE FUNCTION <replaceable>handler_function_name</replaceable> ()
-    RETURNS LANGUAGE_HANDLER AS
-    '<replaceable>path-to-shared-object</replaceable>' LANGUAGE C;
+CREATE FUNCTION <replaceable>handler_function_name</replaceable>()
+    RETURNS language_handler
+    AS '<replaceable>path-to-shared-object</replaceable>'
+    LANGUAGE C;
 </synopsis>
-      The special return type of <type>LANGUAGE_HANDLER</type> tells
-      the database that this function does not return one of
+      The special return type of <type>language_handler</type> tells
+      the database system that this function does not return one of
      the defined <acronym>SQL</acronym> data types and is not directly usable
      in <acronym>SQL</acronym> statements.
     </para>
@@ -99,7 +101,7 @@ CREATE FUNCTION <replaceable>handler_function_name</replaceable> ()
 CREATE <optional>TRUSTED</optional> <optional>PROCEDURAL</optional> LANGUAGE <replaceable>language-name</replaceable>
    HANDLER <replaceable>handler_function_name</replaceable>;
 </synopsis>
-      The optional key word <literal>TRUSTED</literal> tells whether
+      The optional key word <literal>TRUSTED</literal> specifies that
      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
@@ -119,20 +121,12 @@ CREATE <optional>TRUSTED</optional> <optional>PROCEDURAL</optional> LANGUAGE <re
   </procedure>

   <para>
-    In a default <productname>PostgreSQL</productname> installation,
-    the handler for the <application>PL/pgSQL</application> language
-    is built and installed into the <quote>library</quote>
-    directory. If <application>Tcl/Tk</> support is configured in, the handlers for
-    <application>PL/Tcl</> and <application>PL/TclU</> are also built and installed in the same
-    location.  Likewise, the <application>PL/Perl</> and <application>PL/PerlU</> handlers are built
-    and installed if Perl support is configured, and <application>PL/Python</> is
-    installed if Python support is configured.  The
-    <filename>createlang</filename> script automates <xref
-    linkend="xplang-install-cr1"> and <xref
-    linkend="xplang-install-cr2"> described above.
+    <xref linkend="xplang-install-example"> shows how the manual
+    installation procedure would work with the language
+    <application>PL/pgSQL</application>.
   </para>

-   <example>
+   <example id="xplang-install-example">
    <title>Manual Installation of <application>PL/pgSQL</application></title>

     <para>
@@ -140,7 +134,7 @@ CREATE <optional>TRUSTED</optional> <optional>PROCEDURAL</optional> LANGUAGE <re
      shared object for the <application>PL/pgSQL</application> language's call handler function.

 <programlisting>
-CREATE FUNCTION plpgsql_call_handler () RETURNS LANGUAGE_HANDLER AS
+CREATE FUNCTION plpgsql_call_handler() RETURNS language_handler AS
    '$libdir/plpgsql' LANGUAGE C;
 </programlisting>
     </para>
@@ -157,6 +151,17 @@ CREATE TRUSTED PROCEDURAL LANGUAGE plpgsql
     </para>
  </example>

+   <para>
+    In a default <productname>PostgreSQL</productname> installation,
+    the handler for the <application>PL/pgSQL</application> language
+    is built and installed into the <quote>library</quote>
+    directory. If <application>Tcl/Tk</> support is configured in, the handlers for
+    <application>PL/Tcl</> and <application>PL/TclU</> are also built and installed in the same
+    location.  Likewise, the <application>PL/Perl</> and <application>PL/PerlU</> handlers are built
+    and installed if Perl support is configured, and <application>PL/Python</> is
+    installed if Python support is configured.
+   </para>
+
  </sect1>

 </chapter>