A bunch of small doco updates motivated by scanning the comments on

the interactive docs.

doc/src/sgml/arch-pg.sgml

@@ -5,7 +5,7 @@
 <Title><ProductName>Postgres</ProductName> Architectural Concepts</Title>
 
 <Para>
-     Before we continue, you  should  understand  the  basic
+     Before we begin, you  should  understand  the  basic
      <ProductName>Postgres</ProductName>  system  architecture.   Understanding how the
      parts of <ProductName>Postgres</ProductName> interact will make the  next  chapter
      somewhat clearer.
@@ -16,7 +16,7 @@
 <ItemizedList>
 <ListItem>
 <Para>
-      	A supervisory daemon process (<Application>postmaster</Application>),
+      	A supervisory daemon process (the <Application>postmaster</Application>),
 </Para>
 </ListItem>
 <ListItem>
@@ -26,7 +26,7 @@
 </ListItem>
 <ListItem>
 <Para>
-      	the  one or more backend database servers (the <Application>postgres</Application> process itself).
+      	one or more backend database servers (the <Application>postgres</Application> process itself).
 </Para>
 </ListItem>
 </ItemizedList>
@@ -34,9 +34,10 @@
 <Para>
      A single  <Application>postmaster</Application>  manages  a  given  collection  of
      databases  on  a  single  host.   Such  a collection of
-     databases is called a cluster (of databases).   Frontend
+     databases is called a cluster (of databases).   A frontend
-     applications  that  wish  to  access  a  given database
+     application  that  wishes  to  access  a  given database
-     within a cluster make calls to the   library.
+     within a cluster makes calls to an interface library (eg, libpq)
+     that is linked into the application.
      The library sends user requests over the network to the
      <Application>postmaster</Application>
 (<XRef LinkEnd="PGARCH-CONNECTIONS">(a)), 
@@ -58,30 +59,39 @@ which in turn  starts  a  new backend  server  process
 From that  point  on,  the  frontend process and the backend
      server communicate without intervention by the 
      <Application>postmaster</Application>.   Hence, the <Application>postmaster</Application> is always running, waiting
-     for requests, whereas frontend  and  backend  processes
+     for connection requests, whereas frontend  and  backend  processes
      come  and  go.  The <FileName>libpq</FileName> library allows a single 
      frontend to make multiple connections to backend processes.
-     However,  the  frontend  application is still a 
+     However,  each backend process is a single-threaded process that can
-     single-threaded process.  Multithreaded frontend/backend  
+     only execute one query at a time; so the communication over any one
-     connections are not currently supported in <FileName>libpq</FileName>.
+     frontend-to-backend connection is single-threaded.
+</Para>
+
+<Para>
      One  implication of this architecture is that the 
-     <Application>postmaster</Application> and the backend always run on the  same  
+     <Application>postmaster</Application> and the backend always run on the
-     machine (the  database  server), while the frontend 
+     same machine (the  database  server), while the frontend 
      application may run  anywhere.   You  should  keep  this  
      in  mind,
      because  the  files  that  can  be accessed on a client
      machine may not be accessible (or may only be  accessed
-     using  a  different  file name)  on  the database server
+     using  a  different  path name)  on  the database server
      machine.
+</Para>
+
+<Para>
      You should also be aware that the <Application>postmaster</Application> and  
      postgres  servers  run  with  the  user-id  of the <ProductName>Postgres</ProductName>
-     "superuser."  
+     <quote>superuser</>.
 Note that the <ProductName>Postgres</ProductName> superuser does not
-have  to  be  a special user (e.g., a user named 
+have  to  be  any particular user (e.g., a user named 
 <literal>postgres</literal>), although many systems are installed that way.
 Furthermore,  the  <ProductName>Postgres</ProductName>  superuser should
-     definitely  not  be the Unix superuser, <literal>root</literal>!  In any
+definitely  not  be the Unix superuser, <literal>root</literal>!
-     case, all files relating to a database should belong to
+It is safest if the <ProductName>Postgres</ProductName>  superuser is an
+ordinary, unprivileged user so far as the surrounding Unix system is
+concerned.
+     In any case, all files relating to a database should belong to
      this <ProductName>Postgres</ProductName> superuser.
 </Para>
 </sect1>

doc/src/sgml/array.sgml

@@ -1,4 +1,4 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/array.sgml,v 1.13 2001/11/03 21:42:47 tgl Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/array.sgml,v 1.14 2001/11/19 03:58:23 tgl Exp $ -->
 
 <chapter id="arrays">
  <title>Arrays</title>
@@ -19,6 +19,8 @@ CREATE TABLE sal_emp (
     schedule        text[][]
 );
 </programlisting>
+  As shown, an array data type is named by appending square brackets
+  (<literal>[ ]</>) to the data type name of the array elements.
   The above query will create a table named
   <structname>sal_emp</structname> with a <type>text</type> string
   (<structfield>name</structfield>), a one-dimensional array of type
@@ -31,7 +33,7 @@ CREATE TABLE sal_emp (
 
  <para>
   Now we do some <command>INSERT</command>s.  Observe that to write an array
-  value, we enclose the element values within braces and separate them
+  value, we enclose the element values within curly braces and separate them
   by commas.  If you know C, this is not unlike the syntax for
   initializing structures.
      
@@ -63,6 +65,7 @@ SELECT name FROM sal_emp WHERE pay_by_quarter[1] &lt;&gt; pay_by_quarter[2];
 (1 row)
 </programlisting>
 
+  The array subscript numbers are written within square brackets.
   <productname>Postgres</productname> uses the
   <quote>one-based</quote> numbering convention for arrays, that is,
   an array of n elements starts with <literal>array[1]</literal> and
@@ -163,7 +166,7 @@ CREATE TABLE tictactoe (
 
  <para>
   Actually, the current implementation does not enforce the declared
-  number of dimensions either.  Arrays of a particular base type are
+  number of dimensions either.  Arrays of a particular element type are
   all considered to be of the same type, regardless of size or number
   of dimensions.
  </para>
@@ -236,4 +239,13 @@ SELECT * FROM sal_emp WHERE pay_by_quarter **= 10000;
   </para>
  </tip>
 
+ <note>
+  <para>
+   A limitation of the present array implementation is that individual
+   elements of an array cannot be SQL NULLs.  The entire array can be set
+   to NULL, but you can't have an array with some elements NULL and some
+   not.  Fixing this is on the TODO list.
+  </para>
+ </note>
+
 </chapter>

doc/src/sgml/charset.sgml

@@ -1,4 +1,4 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/charset.sgml,v 2.16 2001/11/18 20:33:32 petere Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/charset.sgml,v 2.17 2001/11/19 03:58:24 tgl Exp $ -->
 
 <chapter id="charset">
  <title>Localization</>
@@ -176,11 +176,11 @@ export LANG=sv_SE
     for any particular database cluster, or indexes on text columns will
     become corrupt.  <productname>Postgres</productname> enforces this
     by recording the values of <envar>LC_COLLATE</> and <envar>LC_CTYPE</>
-    that are seen by <command>initdb</>.  The server automatically adopts
+    that are seen by <application>initdb</>.  The server automatically adopts
     those two values when it is started; only the other <envar>LC_</>
     categories can be set from the environment at server startup.
     In short, only one collation order can be used in a database cluster,
-    and it is chosen at <command>initdb</> time.
+    and it is chosen at <application>initdb</> time.
    </para>
   </sect2>
 
@@ -256,6 +256,18 @@ perl: warning: Falling back to the standard locale ("C").
     man page of your system if you are not sure.
    </para>
 
+   <para>
+    Check that <productname>PostgreSQL</> is actually using the locale that
+    you think it is.  <envar>LC_COLLATE</> and <envar>LC_CTYPE</> settings are
+    determined at <application>initdb</> time and cannot be changed without
+    repeating <application>initdb</>.  Other locale settings including
+    <envar>LC_MESSAGES</> and <envar>LC_MONETARY</> are determined by the 
+    environment the postmaster is started in, and can be changed with a simple
+    postmaster restart.  You can check the <envar>LC_COLLATE</> and
+    <envar>LC_CTYPE</> settings of
+    a database with the <filename>contrib/pg_controldata</> utility program.
+   </para>
+
    <para>
     The directory <filename>src/test/locale</> contains a test suite
     for <productname>PostgreSQL</>'s locale support.

doc/src/sgml/client-auth.sgml

@@ -1,4 +1,4 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.27 2001/11/18 23:24:16 tgl Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.28 2001/11/19 03:58:24 tgl Exp $ -->
 
 <chapter id="client-authentication">
  <title>Client Authentication</title>
@@ -541,14 +541,34 @@ local        all                                          md5  admins
     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).
+    --with-krb5</> respectively), although only one version can be
+    supported in any one build.
    </para>
 
    <para>
-    <productname>Postgres</> should operate like a normal Kerberos
+    <productname>Postgres</> operates like a normal Kerberos service.
-    service. The name of the service principal is normally
+    The name of the service principal is
-    <literal>postgres</literal>, unless it was changed during the
+    <replaceable>servicename/hostname@realm</>, where 
-    build. Make sure that your server key file is readable (and
+    <replaceable>servicename</> is <literal>postgres</literal>
+    (unless a different service name was selected at configure time
+    with <literal>./configure --with-krb-srvnam=whatever</>).
+    <replaceable>hostname</> is the fully qualified domain name of the server
+    machine.  The service principal's realm is the preferred realm of the
+    server machine.
+   </para>
+
+   <para>
+    Client principals must have their <productname>Postgres</> username as
+    their first component, for example
+    <replaceable>pgusername/otherstuff@realm</>.
+    At present the realm of the client is not checked by
+    <productname>Postgres</>; so
+    if you have cross-realm authentication enabled, then any principal
+    in any realm that can communicate with yours will be accepted.
+   </para>
+
+   <para>
+    Make sure that your server key file is readable (and
     preferably only readable) by the Postgres server account (see
     <xref linkend="postgres-user">). The location of the key file
     is specified with the <varname>krb_server_keyfile</> run time
@@ -569,49 +589,12 @@ local        all                                          md5  admins
    </para>
 
    <para>
-    In the <productname>Kerberos</> 5 hooks, the following assumptions
+    When connecting to the database make sure you have a ticket for a
-    are made about user and service naming:
+    principal matching the requested database username. 
-
+    An example: For database username <literal>fred</>, both principal
-    <itemizedlist>
+    <literal>fred@EXAMPLE.COM</> and
-     <listitem>
+    <literal>fred/users.example.com@EXAMPLE.COM</> can be
-      <para>
+    used to authenticate to the database server. 
-       User principal names (anames) are assumed to contain the actual
-       Unix/<productname>Postgres</> user name in the first component.
-      </para>
-     </listitem>
-     <listitem>
-      <para>
-       The <productname>Postgres</> service is assumed to be have two
-       components, the service name and a host name, canonicalized as
-       in Version 4 (i.e., with all domain suffixes removed).
-      </para>
-     </listitem>
-    </itemizedlist>
-
-    <informaltable>
-     <tgroup cols="2">
-      <thead>
-       <row>
-        <entry>Parameter</>
-	<entry>Example</>
-       </row>
-      </thead>
-      <tbody>
-       <row>
-	<entry>user</>
-	<entry>frew@S2K.ORG</>
-       </row>
-       <row>
-	<entry>user</>
-	<entry>aoki/HOST=miyu.S2K.Berkeley.EDU@S2K.ORG</>
-       </row>	   
-       <row>
-	<entry>host</>
-	<entry>postgres_dbms/ucbvax@S2K.ORG</>
-       </row>
-      </tbody>
-     </tgroup>
-    </informaltable>
    </para>
 
    <para>

doc/src/sgml/datatype.sgml

@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.69 2001/11/12 21:04:45 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.70 2001/11/19 03:58:22 tgl Exp $
 -->
 
  <chapter id="datatype">
@@ -382,7 +382,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.69 2001/11/12 21:04:45 tg
 	<entry><type>bigint</></entry>
 	<entry>8 bytes</entry>
 	<entry>Very large range fixed-precision</entry>
-	<entry>about 18 decimal digits</entry>
+	<entry>-9223372036854775807 to 9223372036854775807</entry>
        </row>
 
        <row>
@@ -1538,22 +1538,29 @@ January 8 04:05:06 1999 PST
      </indexterm>
 
       <para>
-       <type>interval</type>s can be specified with the following syntax:
+       <type>interval</type> values can be written with the following syntax:
 
 <programlisting>
   Quantity Unit [Quantity Unit...] [Direction]
-@ Quantity Unit [Direction]
+@ Quantity Unit [Quantity Unit...] [Direction]
 </programlisting>
 
-      where: <literal>Quantity</literal> is ..., <literal>-1</literal>,
+      where: <literal>Quantity</literal> is an integer (possibly signed);
-      <literal>0</literal>, <literal>1</literal>, <literal>2</literal>, ...;
       <literal>Unit</literal> is <literal>second</literal>,
       <literal>minute</literal>, <literal>hour</literal>, <literal>day</literal>,
       <literal>week</literal>, <literal>month</literal>, <literal>year</literal>,
       <literal>decade</literal>, <literal>century</literal>, <literal>millennium</literal>,
       or abbreviations or plurals of these units;
       <literal>Direction</literal> can be <literal>ago</literal> or
-      empty.
+      empty.  The at sign (<literal>@</>) is optional noise.  The amounts
+      of different quantities are implicitly added up with appropriate
+      sign accounting.
+     </para>
+
+     <para>
+      Quantities of days, hours, minutes, and seconds can be specified without
+      explicit unit markings: for example, <literal>'1 12:59:10'</> is read
+      the same as <literal>'1 day 12 hours 59 min 10 sec'</>.
      </para>
     </sect3>
 

doc/src/sgml/func.sgml

@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/func.sgml,v 1.80 2001/11/18 21:17:10 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/func.sgml,v 1.81 2001/11/19 03:58:23 tgl Exp $
 Postgres documentation
 -->
 
@@ -825,7 +825,7 @@ Postgres documentation
      </row>
 
      <row>
-      <entry><function>char_length</function>(<parameter>string</parameter>) or character_length(<parameter>string</parameter>)</entry>
+      <entry><function>char_length</function>(<parameter>string</parameter>) or <function>character_length</function>(<parameter>string</parameter>)</entry>
       <entry><type>integer</type></entry>
       <entry>
        length of string
@@ -981,6 +981,25 @@ Postgres documentation
       <entry><literal>Hi Thomas</literal></entry>
      </row>
 
+     <row>
+      <entry><function>length</function>(<parameter>string</parameter>)</entry>
+      <entry><type>integer</type></entry>
+      <entry>
+       length of string
+       <indexterm>
+        <primary>character strings</primary>
+	<secondary>length</secondary>
+       </indexterm>
+       <indexterm>
+        <primary>length</primary>
+	<secondary>character strings</secondary>
+	<see>character strings, length</see>
+       </indexterm>
+      </entry>
+      <entry><literal>length('jose')</></entry>
+      <entry><literal>4</></entry>
+     </row>
+
      <row>
       <entry>
        <function>lpad</function>(<parameter>string</parameter> <type>text</type>,
@@ -4084,6 +4103,32 @@ SELECT NULLIF(value, '(none)') ...
     <literal>TRIGGER</>.  (Case of the string is not significant, however.)
    </para>
 
+   <table>
+    <title>System Information Functions</>
+    <tgroup cols="3">
+     <thead>
+      <row><entry>Name</> <entry>Return Type</> <entry>Description</></row>
+     </thead>
+
+     <tbody>
+      <row>
+       <entry>version</>
+       <entry>text</>
+       <entry>PostgreSQL version information</>
+      </row>
+     </tbody>
+    </tgroup>
+   </table>
+
+   <indexterm zone="functions-misc">
+    <primary>version</primary>
+   </indexterm>
+
+   <para>
+    <function>version()</> returns a string describing the PostgreSQL
+    server's version.
+   </para>
+
   </sect1>
 
 

doc/src/sgml/inherit.sgml

@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/inherit.sgml,v 1.15 2001/09/13 15:55:22 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/Attic/inherit.sgml,v 1.16 2001/11/19 03:58:23 tgl Exp $
 -->
 
  <chapter id="inherit">
@@ -171,6 +171,16 @@ SET SQL_Inheritance TO OFF;
      or add a line in your <filename>postgresql.conf</filename> file.
    </para>
   </note>
+
+  <para>
+   A limitation of the inheritance feature is that indexes (including
+   unique constraints) and foreign key constraints only apply to single
+   tables, not to their inheritance children.  Thus, in the above example,
+   specifying that another table's column <literal>REFERENCES cities(name)</>
+   would allow the other table to contain city names but not capital names.
+   This deficiency will probably be fixed in some future release.
+  </para>
+
  </chapter>
 
 <!-- Keep this comment at the end of the file

doc/src/sgml/install-win32.sgml

@@ -27,7 +27,7 @@
 
  <tip>
   <para>
-   If you are using Windows NT/2000 you can build and use all of
+   If you are using Windows 98 or newer you can build and use all of
    <productname>PostgreSQL</productname> <quote>the Unix way</quote>
    if you install the <productname>Cygwin</productname> toolkit first.
    In that case see <xref linkend="installation">.

doc/src/sgml/installation.sgml

@@ -1,4 +1,4 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v 1.63 2001/10/31 20:35:02 petere Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v 1.64 2001/11/19 03:58:24 tgl Exp $ -->
 
 <chapter id="installation">
  <title><![%standalone-include[<productname>PostgreSQL</>]]>
@@ -162,7 +162,8 @@ su - postgres
   <title>Getting The Source</title>
 
   <para>
-   The <productname>PostgreSQL</> &version; sources can by obtained from <ulink
+   The <productname>PostgreSQL</> &version; sources can be obtained by
+   anonymous FTP from <ulink
    url="ftp://ftp.postgresql.org/pub/postgresql-&version;.tar.gz"></ulink>.
    Use a mirror if possible. Then unpack it:
 <screen>
@@ -904,6 +905,7 @@ All of PostgreSQL is successfully made. Ready to install.
 <screen>
 <userinput>gmake check</userinput>
 </screen>
+    (This won't work as root; do it as an unprivileged user.)
     It is possible that some tests fail, due to differences in error
     message wording or floating point results.
     <![%standalone-include[The file
@@ -1120,7 +1122,7 @@ libpq.so.2.1: cannot open shared object file: No such file or directory
     shell start-up file, such as <filename>~/.bash_profile</> (or
     <filename>/etc/profile</>, if you want it to affect every user):
 <programlisting>
-PATH=$PATH:/usr/local/pgsql/bin
+PATH=/usr/local/pgsql/bin:$PATH
 </programlisting>
     If you are using <command>csh</> or <command>tcsh</>, then use this command:
 <programlisting>
@@ -1137,7 +1139,7 @@ set path = ( /usr/local/pgsql/bin $path )
     documentation, you need to add a line like the following to a
     shell start-up file:
 <programlisting>
-MANPATH=$MANPATH:/usr/local/pgsql/man
+MANPATH=/usr/local/pgsql/man:$MANPATH
 </programlisting>
    </para>
 

doc/src/sgml/libpq++.sgml

@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.33 2001/10/12 23:32:34 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.34 2001/11/19 03:58:24 tgl Exp $
 -->
 
  <chapter id="libpqplusplus">
@@ -217,6 +217,9 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.33 2001/10/12 23:32:
        <synopsis>
 	PgConnection::PgConnection(const char *conninfo)
        </synopsis>
+       The <quote>conninfo</> string is the same as for the underlying
+       libpq <function>PQconnectdb</> function.
+
        Although typically called from one of the access classes, a connection to
        a backend server is possible by creating a <classname>PgConnection</> object.
       </para>

doc/src/sgml/libpq.sgml

@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v 1.76 2001/11/18 21:28:00 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v 1.77 2001/11/19 03:58:23 tgl Exp $
 -->
 
  <chapter id="libpq">
@@ -78,11 +78,12 @@ PGconn *PQconnectdb(const char *conninfo)
 
    <para>
    Each parameter setting is in the form <literal>keyword = value</literal>.
-   (To write a null value or a value containing
+   (To write an empty value or a value containing
    spaces, surround it with single quotes, e.g.,
    <literal>keyword = 'a value'</literal>.
-   Single quotes within the value must be written as <literal>\'</literal>.
+   Single quotes and backslashes within the value must be escaped with a
-   Spaces around the equal sign are optional.)  The currently recognized
+   backslash, e.g., <literal>\'</literal> or <literal>\\</literal>.)
+   Spaces around the equal sign are optional.  The currently recognized
    parameter keywords are:
 
    <variablelist>

doc/src/sgml/manage.sgml

@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/manage.sgml,v 1.18 2001/11/18 00:38:00 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/Attic/manage.sgml,v 1.19 2001/11/19 03:58:24 tgl Exp $
 -->
 
  <Chapter Id="manage">
@@ -90,32 +90,37 @@ ERROR:  CREATE DATABASE: Permission denied.
      Once you have constructed a database, you can access it
      by:
 
-<ItemizedList Mark="bullet" Spacing="compact">
+    <itemizedlist spacing="compact" mark="bullet">
-<ListItem>
+     <listitem>
-<Para>
+      <para>
-running the <ProductName>PostgreSQL</ProductName>  interactive terminal
+       Running the <productname>PostgreSQL</productname> interactive
-<Application>psql</Application> which allows you to interactively
+       terminal program, called <quote>psql</quote>, which allows you
-enter, edit, and execute <Acronym>SQL</Acronym> commands.
+       to interactively enter, edit, and execute
-</Para>
+       <acronym>SQL</acronym> commands.
-</ListItem>
+      </para>
-<ListItem>
+     </listitem>
-<Para>
-writing a  C  program  using  the  <application>LIBPQ</application> subroutine
-library.   This  allows  you  to submit <Acronym>SQL</Acronym> commands
-from C and get answers and status messages  back  to
-your  program.   This interface is discussed further
-in <citetitle>The PostgreSQL Programmer's Guide</citetitle>.
-</Para>
-</ListItem>
-<ListItem>
-<Para>
-writing a program in other languages for which there are available interface
-libraries.
-</Para>
-</ListItem>
-</ItemizedList>
 
-You might want to start up <Application>psql</Application>, 
+     <listitem>
+      <para>
+       Using an existing graphical frontend tool like
+       <application>PgAccess</application> or
+       <application>ApplixWare</application> (via
+       <acronym>ODBC</acronym>) to create and manipulate a database.
+       These possibilities are not covered in this tutorial.
+      </para>
+     </listitem>
+
+     <listitem>
+      <para>
+       Writing a custom application, using one of the several
+       available language bindings.  These possibilities are discussed
+       further in <citetitle>The PostgreSQL Programmer's
+       Guide</citetitle>.
+      </para>
+     </listitem>
+    </itemizedlist>
+
+You probably want to start up <Application>psql</Application>, 
 to try out the examples in this manual.
  It can be activated for the <Database>mydb</Database>
      database by typing the command:
@@ -164,7 +169,7 @@ mydb=> \g
      To read queries from a file,  say  <filename>myFile</filename>,  instead  of
      entering them interactively, type:
 <ProgramListing>
-mydb=> \i fileName
+mydb=> \i myFile
 </ProgramListing>
 
      To get out of <Application>psql</Application> and return to Unix, type

doc/src/sgml/pltcl.sgml

@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/pltcl.sgml,v 2.15 2001/10/13 04:23:50 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/pltcl.sgml,v 2.16 2001/11/19 03:58:24 tgl Exp $
 -->
 
  <chapter id="pltcl">
@@ -463,7 +463,7 @@ spi_exec -array C "SELECT * FROM pg_class" {
      </varlistentry>
 
      <varlistentry>
-      <term><function>spi_exec</> <literal>?-count <replaceable>n</replaceable>? ?-array<replaceable>name</replaceable>? ?-nulls<replaceable>string</replaceable>? <replaceable>queryid</replaceable> ?<replaceable>value-list</replaceable>? ?<replaceable>loop-body</replaceable>?</literal></term>
+      <term><function>spi_execp</> <literal>?-count <replaceable>n</replaceable>? ?-array<replaceable>name</replaceable>? ?-nulls<replaceable>string</replaceable>? <replaceable>queryid</replaceable> ?<replaceable>value-list</replaceable>? ?<replaceable>loop-body</replaceable>?</literal></term>
       <listitem>
        <para>
 	Execute a prepared plan from <function>spi_prepare</> with variable substitution.

doc/src/sgml/pygresql.sgml

@@ -1,4 +1,4 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/Attic/pygresql.sgml,v 1.3 2001/09/13 15:55:23 petere Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/Attic/pygresql.sgml,v 1.4 2001/11/19 03:58:24 tgl Exp $ -->
 
 <chapter id="pygresql">
  <title><application>PyGreSQL</application> - <application>Python</application> Interface</title>
@@ -2671,11 +2671,13 @@ get_attnames(<replaceable>table</replaceable>)
           <variablelist>
             <varlistentry>
               <term>
-                list
+                dictionary
               </term>
               <listitem>
                 <para>
-                  List of attribute names.
+		 The dictionary's keys are
+		 the attribute names, the values are the type names of
+		 the attributes.
                 </para>
               </listitem>
             </varlistentry>
@@ -2687,7 +2689,8 @@ get_attnames(<replaceable>table</replaceable>)
       <refsect1 id="R1-PYGRESQL-DB-GET-ATTNAMES-1">
         <title>Description</title>
         <para>
-          Given the name of a table, digs out the list of attribute names.
+          Given the name of a table, digs out the set of attribute names
+	  and types.
         </para>
       </refsect1>
 

doc/src/sgml/queries.sgml

@@ -1,4 +1,4 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/queries.sgml,v 1.11 2001/11/08 23:40:40 petere Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/queries.sgml,v 1.12 2001/11/19 03:58:24 tgl Exp $ -->
 
 <chapter id="queries">
  <title>Queries</title>
@@ -910,15 +910,21 @@ SELECT a AS b FROM table1 ORDER BY a;
 <synopsis>
 SELECT <replaceable>select_list</replaceable>
     FROM <replaceable>table_expression</replaceable>
-    <optional>ORDER BY <replaceable>sort_spec</replaceable></optional>
     <optional>LIMIT { <replaceable>number</replaceable> | ALL }</optional> <optional>OFFSET <replaceable>number</replaceable></optional>
 </synopsis>
 
   <para>
    LIMIT allows you to retrieve just a portion of the rows that are
    generated by the rest of the query.  If a limit count is given, no
-   more than that many rows will be returned.  If an offset is given,
+   more than that many rows will be returned.
-   that many rows will be skipped before starting to return rows.
+   LIMIT ALL is the same as omitting a LIMIT clause.
+  </para>
+
+  <para>
+   OFFSET says to skip that many rows before beginning to return rows
+   to the client.  OFFSET 0 is the same as omitting an OFFSET clause.
+   If both OFFSET and LIMIT appear, then OFFSET rows are skipped before
+   starting to count the LIMIT rows that are returned.
   </para>
 
   <para>

doc/src/sgml/ref/create_trigger.sgml

@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_trigger.sgml,v 1.17 2001/09/13 18:17:44 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_trigger.sgml,v 1.18 2001/11/19 03:58:25 tgl Exp $
 Postgres documentation
 -->
 
@@ -44,7 +44,7 @@ CREATE TRIGGER <replaceable class="PARAMETER">name</replaceable> { BEFORE | AFTE
       <term><replaceable class="parameter">name</replaceable></term>
       <listitem>
        <para>
-	The name of an existing trigger.
+	The name to give the new trigger.
        </para>
       </listitem>
      </varlistentry>
@@ -52,7 +52,7 @@ CREATE TRIGGER <replaceable class="PARAMETER">name</replaceable> { BEFORE | AFTE
       <term><replaceable class="parameter">table</replaceable></term>
       <listitem>
        <para>
-	The name of a table.
+	The name of an existing table.
        </para>
       </listitem>
      </varlistentry>

doc/src/sgml/ref/drop_function.sgml

@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_function.sgml,v 1.14 2001/09/13 19:40:34 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_function.sgml,v 1.15 2001/11/19 03:58:25 tgl Exp $
 Postgres documentation
 -->
 
@@ -36,7 +36,7 @@ DROP FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceable
    <para>
     <variablelist>
      <varlistentry>
-      <term><replaceable class="parameter"> name</replaceable></term>
+      <term><replaceable class="parameter">name</replaceable></term>
       <listitem>
        <para>
 	The name of an existing function.
@@ -47,7 +47,7 @@ DROP FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceable
       <term><replaceable class="parameter">type</replaceable></term>
       <listitem>
        <para>
-	The type of function parameters.
+	The type of the function's parameters.
        </para>
       </listitem>
      </varlistentry>
@@ -99,11 +99,11 @@ NOTICE RemoveFunction: Function "<replaceable class="parameter">name</replaceabl
    Description
   </title>
   <para>
-   DROP FUNCTION will remove references to an existing C
+   DROP FUNCTION will remove the definition of an existing
    function. To execute this command the user must be the
    owner of the function. The input argument types to the
-   function must be specified, as only the function with the
+   function must be specified, since several different functions
-   given name and argument types will be removed.
+   may exist with the same name and different argument lists.
   </para>
  </refsect1>
 
@@ -117,8 +117,8 @@ NOTICE RemoveFunction: Function "<replaceable class="parameter">name</replaceabl
    </para>
 
    <para>
-    No checks are made to ensure that types, operators or access
+    No checks are made to ensure that types, operators, access
-    methods that rely on the function have been removed first.
+    methods, or triggers that rely on the function have been removed first.
    </para>
  </refsect1>
 

doc/src/sgml/ref/pg_ctl-ref.sgml

@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.9 2001/09/21 21:10:56 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.10 2001/11/19 03:58:25 tgl Exp $
 Postgres documentation
 -->
 
@@ -103,9 +103,11 @@ Postgres documentation
    shutdown methods can be selected with the <option>-m</option>
    option: <quote>Smart</quote> mode waits for all the clients to
    disconnect.  This is the default.  <quote>Fast</quote> mode does
-   not wait for clients to disconnect.  All active transactions will
+   not wait for clients to disconnect.  All active transactions are
-   be rolled back.  <quote>Immediate</quote> mode will abort without
+   rolled back and clients are forcibly disconnected, then the
-   complete shutdown.  This will lead to a recovery run on restart.
+   database is shut down.  <quote>Immediate</quote> mode will abort
+   all server processes without clean shutdown.  This will lead to a recovery
+   run on restart.
   </para>
 
   <para>
@@ -337,7 +339,7 @@ Command line was:
 
   <para>
    Waiting for complete start is not a well-defined operation and may
-   fail if access control is set up in way that a local client cannot
+   fail if access control is set up so that a local client cannot
    connect without manual interaction.  It should be avoided.
   </para>
  </refsect1>

doc/src/sgml/ref/pg_restore.sgml

@@ -1,4 +1,4 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.18 2001/10/23 22:11:22 tgl Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.19 2001/11/19 03:58:25 tgl Exp $ -->
 
 <refentry id="APP-PGRESTORE">
  <docinfo>
@@ -584,7 +584,7 @@ connectDBStart() -- connect() failed: No such file or directory
    To reorder database items, it is first necessary to dump the table of
    contents of the archive:
 <screen>
-<prompt>$</prompt> <userinput>pg_restore archive.file -l &gt; archive.list</userinput>
+<prompt>$</prompt> <userinput>pg_restore -l archive.file &gt; archive.list</userinput>
 </screen>
    The listing file consists of a header and one line for each item, e.g.,
 <programlisting>
@@ -628,7 +628,7 @@ connectDBStart() -- connect() failed: No such file or directory
    could be used as input to <command>pg_restore</command> and would only restore
    items 10 and 6, in that order.
 <screen>
-<prompt>$</prompt> <userinput>pg_restore archive.file -L archive.list</userinput>
+<prompt>$</prompt> <userinput>pg_restore -L archive.list archive.file</userinput>
 </screen>
   </para>
 

doc/src/sgml/runtime.sgml

@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.94 2001/11/12 19:19:39 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.95 2001/11/19 03:58:24 tgl Exp $
 -->
 
 <Chapter Id="runtime">
@@ -324,8 +324,8 @@ su - postgres -c "/usr/local/pgsql/bin/pg_ctl start -l logfile -D /usr/local/pgs
 FATAL: StreamServerPort: bind() failed: Address already in use
         Is another postmaster already running on that port?
 </screen>
-     This usually means just what it suggests: you accidentally
+     This usually means just what it suggests: you tried to
-     started a second postmaster on the same port where one is already
+     start a second postmaster on the same port where one is already
      running. However, if the kernel error message is not
      <computeroutput>Address already in use</computeroutput> or some
      variant of that wording, there may be a different problem. For

doc/src/sgml/trigger.sgml

@@ -20,7 +20,7 @@
    </para>
 
    <para>
-    The trigger function must be created before the trigger is created as a
+    The trigger function must be defined before the trigger is created as a
     function taking no arguments and returning opaque.  If the function is
     written in C, it must use the <quote>version 1</> function manager interface.
    </para>

src/interfaces/python/README

@@ -976,9 +976,10 @@ The following describes the methods and variables of this class.
  Parameters: 
    table - name of table
  Returns:
-   List of attribute names
+   Dictionary of attribute names (the names are the keys, the values
+   are the names of the attributes' types)
  Description:
-   Given the name of a table, digs out the list of attribute names.
+   Given the name of a table, digs out the set of attribute names.
 
  3.6. get - get a tuple from a database table
  --------------------------------------------