Editorial improvements for recent plpython doc updates.

diff --git a/doc/src/sgml/plpython.sgml b/doc/src/sgml/plpython.sgml
index 4a118ebd67f515e005f1f71728f87de08931a1ad..23e2dfeba9df20c222fe7bb854f1b6994527a1a8 100644 (file)
--- a/doc/src/sgml/plpython.sgml
+++ b/doc/src/sgml/plpython.sgml
@@ -1,4 +1,4 @@
-
+
 
 
  PL/Python - Python Procedural Language
@@ -61,11 +61,11 @@ $$ LANGUAGE plpythonu;
 
   
    The body of a function is simply a Python script. When the function
-   is called, all unnamed arguments are passed as elements to the array
-   args[] and named arguments as ordinary variables to the
-   Python script. The result is returned from the Python code in the usual way,
-   with return or yield (in case of
-   a resultset statement).
+   is called, its arguments are passed as elements of the array
+   args[]; named arguments are also passed as ordinary
+   variables to the Python script. The result is returned from the Python code
+   in the usual way, with return or
+   yield (in case of a resultset statement).
   
 
   
@@ -101,9 +101,9 @@ def __plpython_procedure_pymax_23456():
    the global args list.  In the
    pymax example, args[0] contains
    whatever was passed in as the first argument and
-   args[1] contains the second argument's value. Alternatively,
-   one can use named parameters as shown in the example above. This greatly simplifies
-   the reading and writing of PL/Python code.
+   args[1] contains the second argument's
+   value. Alternatively, one can use named parameters as shown in the example
+   above.  Use of named parameters is usually more readable.
   
 
   
@@ -161,31 +161,27 @@ $$ LANGUAGE plpythonu;
 
   
    There are multiple ways to return row or composite types from a Python
-   scripts. In following examples we assume to have:
+   function. The following examples assume we have:
 
 
-CREATE TABLE named_value (
-  name   text,
-  value  integer
-);
-
-   or
-
 CREATE TYPE named_value AS (
   name   text,
   value  integer
 );
 
 
+   A composite result can be returned as a:
+
    
     
-     Sequence types (tuple or list), but not set (because
+     Sequence type (a tuple or list, but not a set because
      it is not indexable)
      
       
-       Returned sequence objects must have the same number of items as
-       composite types have fields. Item with index 0 is assigned to the first field
-       of the composite type, 1 to second and so on. For example:
+       Returned sequence objects must have the same number of items as the
+       composite result type has fields. The item with index 0 is assigned to
+       the first field of the composite type, 1 to the second and so on. For
+       example:
 
 
 CREATE FUNCTION make_pair (name text, value integer)
@@ -196,7 +192,7 @@ AS $$
 $$ LANGUAGE plpythonu;
 
 
-       To return SQL null in any column, insert None at
+       To return a SQL null for any column, insert None at
        the corresponding position.
       
      
@@ -206,8 +202,8 @@ $$ LANGUAGE plpythonu;
      Mapping (dictionary)
      
       
-       Value for a composite type's column is retrieved from the mapping with
-       the column name as key. Example:
+       The value for each result type column is retrieved from the mapping
+       with the column name as key. Example:
 
 
 CREATE FUNCTION make_pair (name text, value integer)
@@ -217,8 +213,9 @@ AS $$
 $$ LANGUAGE plpythonu;
 
 
-       Additional dictionary key/value pairs are ignored. Missing keys are
-       treated as errors, i.e. to return an SQL null value for any column, insert
+       Any extra dictionary key/value pairs are ignored. Missing keys are
+       treated as errors.
+       To return a SQL null value for any column, insert
        None with the corresponding column name as the key.
       
      
@@ -228,6 +225,7 @@ $$ LANGUAGE plpythonu;
      Object (any object providing method __getattr__)
      
       
+       This works the same as a mapping.
        Example:
 
 
@@ -261,9 +259,9 @@ $$ LANGUAGE plpythonu;
 
   
    A PL/Python function can also return sets of
-   scalar or composite types. There are serveral ways to achieve this because
-   the returned object is internally turned into an iterator. For following
-   examples, let's assume to have composite type:
+   scalar or composite types. There are several ways to achieve this because
+   the returned object is internally turned into an iterator. The following
+   examples assume we have composite type:
 
 
 CREATE TYPE greeting AS (
@@ -272,10 +270,11 @@ CREATE TYPE greeting AS (
 );
 
    
-   Currently known iterable types are:
+   A set result can be returned from a:
+
    
     
-     Sequence types (tuple, list, set)
+     Sequence type (tuple, list, set)
      
       
 
@@ -341,9 +340,10 @@ $$ LANGUAGE plpythonu;
          bug #1483133,
          some debug versions of Python 2.4
          (configured and compiled with option --with-pydebug)
-         are known to crash the PostgreSQL server.
+         are known to crash the PostgreSQL server
+         when using an iterator to return a set result.
          Unpatched versions of Fedora 4 contain this bug.
-         It does not happen in production version of Python or on patched
+         It does not happen in production versions of Python or on patched
          versions of Fedora 4.
         
        
@@ -351,9 +351,6 @@ $$ LANGUAGE plpythonu;
      
     
    
-
-   Whenever new iterable types are added to Python language,
-   PL/Python is ready to use it.