Big editing for consistent content and presentation.

doc/src/sgml/advanced.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/advanced.sgml,v 1.32 2003/02/19 04:06:27 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/advanced.sgml,v 1.33 2003/03/13 01:30:24 petere Exp $
 -->
 
  <chapter id="tutorial-advanced">
@@ -344,14 +344,14 @@ SELECT name, altitude
 
     which returns:
 
-    <screen>
+<screen>
    name    | altitude
 -----------+----------
  Las Vegas |     2174
  Mariposa  |     1953
  Madison   |      845
 (3 rows)
-    </screen>
+</screen>
    </para>
 
    <para>

doc/src/sgml/array.sgml

-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/array.sgml,v 1.24 2002/11/11 20:14:02 petere Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/array.sgml,v 1.25 2003/03/13 01:30:26 petere Exp $ -->
 
 <sect1 id="arrays">
  <title>Arrays</title>
@@ -10,8 +10,14 @@
  <para>
   <productname>PostgreSQL</productname> allows columns of a table to be
   defined as variable-length multidimensional arrays. Arrays of any
-  built-in type or user-defined type can be created.  To illustrate
-  their use, we create this table:
+  built-in type or user-defined type can be created.
+ </para>
+
+ <sect2>
+  <title>Declaration of Array Types</title>
+
+ <para>
+  To illustrate the use of array types, we create this table:
 <programlisting>
 CREATE TABLE sal_emp (
     name            text,
@@ -20,24 +26,27 @@ CREATE TABLE sal_emp (
 );
 </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 command will create a table named
-  <structname>sal_emp</structname> with columns including
-  a <type>text</type> string (<structfield>name</structfield>),
-  a one-dimensional array of type
-  <type>integer</type> (<structfield>pay_by_quarter</structfield>),
-  which represents the employee's salary by quarter, and a
-  two-dimensional array of <type>text</type>
-  (<structfield>schedule</structfield>), which represents the
-  employee's weekly schedule.
+  (<literal>[]</>) to the data type name of the array elements.  The
+  above command will create a table named
+  <structname>sal_emp</structname> with a column of type
+  <type>text</type> (<structfield>name</structfield>), a
+  one-dimensional array of type <type>integer</type>
+  (<structfield>pay_by_quarter</structfield>), which represents the
+  employee's salary by quarter, and a two-dimensional array of
+  <type>text</type> (<structfield>schedule</structfield>), which
+  represents the employee's weekly schedule.
  </para>
+ </sect2>
+
+ <sect2>
+  <title>Array Value Input</title>
 
  <para>
-  Now we do some <command>INSERT</command>s.  Observe that to write an array
+  Now we can show some <command>INSERT</command> statements.  To write an array
   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.  (More details appear below.)
-     
+
 <programlisting>
 INSERT INTO sal_emp
     VALUES ('Bill',
@@ -51,8 +60,21 @@ INSERT INTO sal_emp
 </programlisting>
  </para>
 
+ <note>
+  <para>
+   A limitation of the present array implementation is that individual
+   elements of an array cannot be SQL null values.  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 to-do list.
+  </para>
+ </note>
+ </sect2>
+
+ <sect2>
+  <title>Array Value References</title>
+
  <para>
-  Now, we can run some queries on <structname>sal_emp</structname>.
+  Now, we can run some queries on the table.
   First, we show how to access a single element of an array at a time.
   This query retrieves the names of the employees whose pay changed in
   the second quarter:
@@ -91,7 +113,7 @@ SELECT pay_by_quarter[3] FROM sal_emp;
   We can also access arbitrary rectangular slices of an array, or
   subarrays.  An array slice is denoted by writing
   <literal><replaceable>lower-bound</replaceable>:<replaceable>upper-bound</replaceable></literal>
-  for one or more array dimensions.  This query retrieves the first
+  for one or more array dimensions.  For example, this query retrieves the first
   item on Bill's schedule for the first two days of the week:
      
 <programlisting>
@@ -109,7 +131,7 @@ SELECT schedule[1:2][1:1] FROM sal_emp WHERE name = 'Bill';
 SELECT schedule[1:2][1] FROM sal_emp WHERE name = 'Bill';
 </programlisting>
 
-  with the same result.  An array subscripting operation is taken to
+  with the same result.  An array subscripting operation is always taken to
   represent an array slice if any of the subscripts are written in the
   form
   <literal><replaceable>lower</replaceable>:<replaceable>upper</replaceable></literal>.
@@ -199,10 +221,15 @@ SELECT array_dims(schedule) FROM sal_emp WHERE name = 'Carol';
   array_lower</function> return the upper/lower bound of the
   given array dimension, respectively.
  </para>
+ </sect2>
+
+ <sect2>
+  <title>Searching in Arrays</title>
 
  <para>
   To search for a value in an array, you must check each value of the
-  array. This can be done by hand (if you know the size of the array):
+  array. This can be done by hand (if you know the size of the array).
+  For example:
 
 <programlisting>
 SELECT * FROM sal_emp WHERE pay_by_quarter[1] = 10000 OR
@@ -212,8 +239,8 @@ SELECT * FROM sal_emp WHERE pay_by_quarter[1] = 10000 OR
 </programlisting>
 
   However, this quickly becomes tedious for large arrays, and is not
-  helpful if the size of the array is unknown. Although it is not part
-  of the primary <productname>PostgreSQL</productname> distribution,
+  helpful if the size of the array is unknown. Although it is not built
+  into <productname>PostgreSQL</productname>,
   there is an extension available that defines new functions and
   operators for iterating over array values. Using this, the above
   query could be:
@@ -222,7 +249,7 @@ SELECT * FROM sal_emp WHERE pay_by_quarter[1] = 10000 OR
 SELECT * FROM sal_emp WHERE pay_by_quarter[1:4] *= 10000;
 </programlisting>
 
-  To search the entire array (not just specified columns), you could
+  To search the entire array (not just specified slices), you could
   use:
 
 <programlisting>
@@ -249,18 +276,11 @@ SELECT * FROM sal_emp WHERE pay_by_quarter **= 10000;
    Tables can obviously be searched easily.
   </para>
  </tip>
+ </sect2>
 
- <note>
-  <para>
-   A limitation of the present array implementation is that individual
-   elements of an array cannot be SQL null values.  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 to-do list.
-  </para>
- </note>
+ <sect2>
+  <title>Array Input and Output Syntax</title>
 
- <formalpara>
-  <title>Array input and output syntax.</title>
   <para>
    The external representation of an array value consists of items that
    are interpreted according to the I/O conversion rules for the array's
@@ -280,10 +300,11 @@ SELECT * FROM sal_emp WHERE pay_by_quarter **= 10000;
    is not ignored, however: after skipping leading whitespace, everything
    up to the next right brace or delimiter is taken as the item value.
   </para>
- </formalpara>
+ </sect2>
+
+ <sect2>
+  <title>Quoting Array Elements</title>
 
- <formalpara>
-  <title>Quoting array elements.</title>
   <para>
    As shown above, when writing an array value you may write double
    quotes around any individual array
@@ -295,7 +316,6 @@ SELECT * FROM sal_emp WHERE pay_by_quarter **= 10000;
    Alternatively, you can use backslash-escaping to protect all data characters
    that would otherwise be taken as array syntax or ignorable white space.
   </para>
- </formalpara>
 
   <para>
    The array output routine will put double quotes around element values
@@ -308,7 +328,7 @@ SELECT * FROM sal_emp WHERE pay_by_quarter **= 10000;
    <productname>PostgreSQL</productname> releases.)
   </para>
 
- <tip>
+ <note>
   <para>
    Remember that what you write in an SQL command will first be interpreted
    as a string literal, and then as an array.  This doubles the number of
@@ -325,6 +345,7 @@ INSERT ... VALUES ('{"\\\\","\\""}');
    <type>bytea</> for example, we might need as many as eight backslashes
    in the command to get one backslash into the stored array element.)
   </para>
- </tip>
+ </note>
+ </sect2>
 
 </sect1>

doc/src/sgml/charset.sgml

-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/charset.sgml,v 2.31 2003/01/19 00:13:28 momjian Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/charset.sgml,v 2.32 2003/03/13 01:30:26 petere Exp $ -->
 
 <chapter id="charset">
  <title>Localization</>
@@ -75,7 +75,7 @@
     <command>initdb</command> exactly which locale you want with the
     option <option>--locale</option>.  For example:
 <screen>
-<prompt>$ </><userinput>initdb --locale=sv_SE</>
+initdb --locale=sv_SE
 </screen>
    </para>
 
@@ -517,7 +517,7 @@ perl: warning: Falling back to the standard locale ("C").
      for a <productname>PostgreSQL</productname> installation. For example:
 
 <screen>
-$ <userinput>initdb -E EUC_JP</>
+initdb -E EUC_JP
 </screen>
 
      sets the default encoding to <literal>EUC_JP</literal> (Extended Unix Code for Japanese).
@@ -531,7 +531,7 @@ $ <userinput>initdb -E EUC_JP</>
      You can create a database with a different encoding:
 
 <screen>
-$ <userinput>createdb -E EUC_KR korean</>
+createdb -E EUC_KR korean
 </screen>
 
      will create a database named <database>korean</database> with <literal>EUC_KR</literal> encoding.

doc/src/sgml/ddl.sgml

-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ddl.sgml,v 1.12 2003/02/19 04:06:27 momjian Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ddl.sgml,v 1.13 2003/03/13 01:30:28 petere Exp $ -->
 
 <chapter id="ddl">
  <title>Data Definition</title>
@@ -171,9 +171,9 @@ DROP TABLE products;
       The object identifier (object ID) of a row.  This is a serial
       number that is automatically added by
       <productname>PostgreSQL</productname> to all table rows (unless
-      the table was created <literal>WITHOUT OIDS</literal>, in which
+      the table was created using <literal>WITHOUT OIDS</literal>, in which
       case this column is not present).  This column is of type
-      <literal>oid</literal> (same name as the column); see <xref
+      <type>oid</type> (same name as the column); see <xref
       linkend="datatype-oid"> for more information about the type.
      </para>
     </listitem>
@@ -183,7 +183,7 @@ DROP TABLE products;
     <term><structfield>tableoid</></term>
     <listitem>
      <para>
-      The OID of the table containing this row.  This attribute is
+      The OID of the table containing this row.  This column is
       particularly handy for queries that select from inheritance
       hierarchies, since without it, it's difficult to tell which
       individual table a row came from.  The
@@ -221,7 +221,7 @@ DROP TABLE products;
     <listitem>
      <para>
       The identity (transaction ID) of the deleting transaction, or
-      zero for an undeleted tuple.  It is possible for this field to
+      zero for an undeleted tuple.  It is possible for this column to
       be nonzero in a visible tuple: That usually indicates that the
       deleting transaction hasn't committed yet, or that an attempted
       deletion was rolled back.
@@ -254,9 +254,42 @@ DROP TABLE products;
     </listitem>
    </varlistentry>
   </variablelist>
+
+   <para>
+    OIDs are 32-bit quantities and are assigned from a single cluster-wide
+    counter.  In a large or long-lived database, it is possible for the
+    counter to wrap around.  Hence, it is bad practice to assume that OIDs
+    are unique, unless you take steps to ensure that they are unique.
+    Recommended practice when using OIDs for row identification is to create
+    a unique constraint on the OID column of each table for which the OID will
+    be used.  Never assume that OIDs are unique across tables; use the
+    combination of <structfield>tableoid</> and row OID if you need a
+    database-wide identifier.  (Future releases of
+    <productname>PostgreSQL</productname> are likely to use a separate
+    OID counter for each table, so that <structfield>tableoid</>
+    <emphasis>must</> be included to arrive at a globally unique identifier.)
+   </para>
+
+   <para>
+    Transaction identifiers are also 32-bit quantities.  In a long-lived
+    database it is possible for transaction IDs to wrap around.  This
+    is not a fatal problem given appropriate maintenance procedures;
+    see the &cite-admin; for details.  However, it is
+    unwise to depend on uniqueness of transaction IDs over the long term
+    (more than one billion transactions).
+   </para>
+
+   <para>
+    Command
+    identifiers are also 32-bit quantities.  This creates a hard limit
+    of 2<superscript>32</> (4 billion) <acronym>SQL</acronym> commands
+    within a single transaction.  In practice this limit is not a
+    problem --- note that the limit is on number of
+    <acronym>SQL</acronym> commands, not number of tuples processed.
+   </para>
  </sect1>
 
- <sect1>
+ <sect1 id="ddl-default">
   <title>Default Values</title>
 
   <para>
@@ -279,7 +312,7 @@ DROP TABLE products;
    data type.  For example:
 <programlisting>
 CREATE TABLE products (
-    product_no integer PRIMARY KEY,
+    product_no integer,
     name text,
     price numeric <emphasis>DEFAULT 9.99</emphasis>
 );
@@ -1194,7 +1227,7 @@ GRANT SELECT ON accounts TO GROUP staff;
 REVOKE ALL ON accounts FROM PUBLIC;
 </programlisting>
    The special privileges of the table owner (i.e., the right to do
-   <command>DROP</>, <command>GRANT</>, <command>REVOKE</>, etc)
+   <command>DROP</>, <command>GRANT</>, <command>REVOKE</>, etc.)
    are always implicit in being the owner,
    and cannot be granted or revoked.  But the table owner can choose
    to revoke his own ordinary privileges, for example to make a
@@ -1214,7 +1247,7 @@ REVOKE ALL ON accounts FROM PUBLIC;
   </indexterm>
 
   <para>
-   A <productname>PostgreSQL</productname> database cluster (installation)
+   A <productname>PostgreSQL</productname> database cluster
    contains one or more named databases.  Users and groups of users are
    shared across the entire cluster, but no other data is shared across
    databases.  Any given client connection to the server can access
@@ -1536,10 +1569,10 @@ REVOKE CREATE ON public FROM PUBLIC;
     no longer true: you may create such a table name if you wish, in
     any non-system schema.  However, it's best to continue to avoid
     such names, to ensure that you won't suffer a conflict if some
-    future version defines a system catalog named the same as your
+    future version defines a system table named the same as your
     table.  (With the default search path, an unqualified reference to
-    your table name would be resolved as the system catalog instead.)
-    System catalogs will continue to follow the convention of having
+    your table name would be resolved as the system table instead.)
+    System tables will continue to follow the convention of having
     names beginning with <literal>pg_</>, so that they will not
     conflict with unqualified user-table names so long as users avoid
     the <literal>pg_</> prefix.
@@ -1681,7 +1714,8 @@ REVOKE CREATE ON public FROM PUBLIC;
    linkend="ddl-constraints-fk">, with the orders table depending on
    it, would result in an error message such as this:
 <screen>
-<userinput>DROP TABLE products;</userinput>
+DROP TABLE products;
+
 NOTICE:  constraint $1 on table orders depends on table products
 ERROR:  Cannot drop table products because other objects depend on it
         Use DROP ... CASCADE to drop the dependent objects too

doc/src/sgml/features.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/features.sgml,v 2.17 2003/01/15 21:55:52 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/features.sgml,v 2.18 2003/03/13 01:30:28 petere Exp $
 -->
 
 <appendix id="features">
@@ -105,7 +105,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/features.sgml,v 2.17 2003/01/15 21:55:52 mo
 
    <para>
     The following features defined in <acronym>SQL99</acronym> are not
-    implemented in the current release of
+    implemented in this release of
     <productname>PostgreSQL</productname>. In a few cases, equivalent
     functionality is available.
 

doc/src/sgml/installation.sgml

-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v 1.128 2003/01/19 00:13:28 momjian Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v 1.129 2003/03/13 01:30:28 petere Exp $ -->
 
 <chapter id="installation">
  <title><![%standalone-include[<productname>PostgreSQL</>]]>
@@ -69,7 +69,7 @@ su - postgres
       <acronym>GNU</> <application>make</> is often installed under
       the name <filename>gmake</filename>; this document will always
       refer to it by that name. (On some systems
-      <acronym>GNU</acronym> make is the default tool with the name
+      <acronym>GNU</acronym> <application>make</> is the default tool with the name
       <filename>make</>.) To test for <acronym>GNU</acronym>
       <application>make</application> enter
 <screen>
@@ -91,8 +91,8 @@ su - postgres
     <listitem>
      <para>
       <application>gzip</> is needed to unpack the distribution in the
-      first place.  If you are reading this, you probably already got
-      past that hurdle.
+      first place.<![%standalone-include;[  If you are reading this, you probably already got
+      past that hurdle.]]>
      </para>
     </listitem>
 
@@ -108,7 +108,7 @@ su - postgres
       specify the <option>--without-readline</option> option for
       <filename>configure</>.  (On <productname>NetBSD</productname>,
       the <filename>libedit</filename> library is
-      <productname>readline</productname>-compatible and is used if
+      <productname>Readline</productname>-compatible and is used if
       <filename>libreadline</filename> is not found.)
      </para>
     </listitem>
@@ -259,7 +259,7 @@ JAVACMD=$JAVA_HOME/bin/java
       <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
+      If you are using the <application>Gettext</> implementation in
       the <acronym>GNU</acronym> 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
@@ -278,7 +278,7 @@ JAVACMD=$JAVA_HOME/bin/java
   </para>
 
   <para>
-   If you are build from a <acronym>CVS</acronym> tree instead of
+   If you are building from a <acronym>CVS</acronym> tree instead of
    using a released source package, or if you want to do development,
    you also need the following packages:
 
@@ -427,7 +427,7 @@ JAVACMD=$JAVA_HOME/bin/java
 </screen>
      Versions prior to 7.0 do not have this
      <filename>postmaster.pid</> file. If you are using such a version
-     you must find out the process id of the server yourself, for
+     you must find out the process ID of the server yourself, for
      example by typing <userinput>ps ax | grep postmaster</>, and
      supply it to the <command>kill</> command.
     </para>
@@ -732,7 +732,7 @@ JAVACMD=$JAVA_HOME/bin/java
 
         <para>
          To use this option, you will need an implementation of the
-         <application>gettext</> API; see above.
+         <application>Gettext</> API; see above.
         </para>
        </listitem>
       </varlistentry>
@@ -1082,7 +1082,7 @@ All of PostgreSQL is successfully made. Ready to install.
 <screen>
 <userinput>gmake -C src/interfaces/python install</userinput>
 </screen>
-    If you do not have superuser access you are on your own: 
+    If you do not have root access you are on your own: 
     you can still take the required files and place them in 
     other directories where Python can find them, but how to 
     do that is left as an exercise.
@@ -1133,7 +1133,7 @@ All of PostgreSQL is successfully made. Ready to install.
    <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
+    clean</>. This will preserve the files made by the <command>configure</command>
     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
@@ -1143,8 +1143,8 @@ All of PostgreSQL is successfully made. Ready to install.
   </formalpara>
 
   <para>
-   If you perform a build and then discover that your configure
-   options were wrong, or if you change anything that configure
+   If you perform a build and then discover that your <command>configure</>
+   options were wrong, or if you change anything that <command>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
@@ -1207,7 +1207,7 @@ setenv LD_LIBRARY_PATH /usr/local/pgsql/lib
    <para>
     On <systemitem class="osname">Cygwin</systemitem>, put the library
     directory in the <envar>PATH</envar> or move the
-    <filename>.dll</filename> files into the <filename>bin/</filename>
+    <filename>.dll</filename> files into the <filename>bin</filename>
     directory.
    </para>
 
@@ -1283,7 +1283,7 @@ set path = ( /usr/local/pgsql/bin $path )
      <seealso>man pages</seealso>
     </indexterm>
     To enable your system to find the <application>man</>
-    documentation, you need to add a line like the following to a
+    documentation, you need to add lines like the following to a
     shell start-up file unless you installed into a location that is
     searched by default.
 <programlisting>
@@ -1544,8 +1544,8 @@ gunzip -c user.ps.gz \
 	<entry>7.3</entry>
         <entry>2002-10-28,
 	 10.20 Tom Lane (<email>tgl@sss.pgh.pa.us</email>),
-	 11.00, 11.11, 32 &amp; 64 bit, Giles Lean (<email>giles@nemeton.com.au</email>)</entry>
-        <entry>gcc and cc; see also <filename>doc/FAQ_HPUX</filename></entry>
+	 11.00, 11.11, 32 and 64 bit, Giles Lean (<email>giles@nemeton.com.au</email>)</entry>
+        <entry><command>gcc</> and <command>cc</>; see also <filename>doc/FAQ_HPUX</filename></entry>
        </row>
        <row>
 	<entry><systemitem class="osname">IRIX</></entry>
@@ -1585,7 +1585,7 @@ gunzip -c user.ps.gz \
 	<entry>7.3</entry>
 	<entry>2002-11-19,
 	 Permaine Cheung <email>pcheung@redhat.com</email>)</entry>
-	<entry>#undef HAS_TEST_AND_SET, remove slock_t typedef</entry>
+	<entry><literal>#undef HAS_TEST_AND_SET</>, remove <type>slock_t</> <literal>typedef</></entry>
        </row>
        <row>
 	<entry><systemitem class="osname">Linux</></entry>
@@ -1715,7 +1715,7 @@ gunzip -c user.ps.gz \
         <entry><systemitem>x86</></entry>
         <entry>7.3.1</entry>
         <entry>2002-12-11, Shibashish Satpathy (<email>shib@postmark.net</>)</entry>
-        <entry>5.0.4, gcc;  see also <filename>doc/FAQ_SCO</filename></entry>
+        <entry>5.0.4, <command>gcc</>;  see also <filename>doc/FAQ_SCO</filename></entry>
        </row>
        <row>
 	<entry><systemitem class="osname">Solaris</></entry>
@@ -1723,7 +1723,7 @@ gunzip -c user.ps.gz \
 	<entry>7.3</entry>
 	<entry>2002-10-28,
 	 Andrew Sullivan (<email>andrew@libertyrms.info</email>)</entry>
-	<entry>Solaris 7 &amp; 8; see also <filename>doc/FAQ_Solaris</filename></entry>
+	<entry>Solaris 7 and 8; see also <filename>doc/FAQ_Solaris</filename></entry>
        </row>
        <row>
 	<entry><systemitem class="osname">Solaris</></entry>
@@ -1813,7 +1813,7 @@ gunzip -c user.ps.gz \
 	<entry>7.2</entry>
 	<entry>2001-11-29,
 	 Cyril Velter (<email>cyril.velter@libertysurf.fr</email>)</entry>
-        <entry>needs updates to semaphore code</entry>
+	<entry>needs updates to semaphore code</entry>
        </row>
      <row>
       <entry><systemitem class="osname">DG/UX 5.4R4.11</></entry>

doc/src/sgml/manage-ag.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/manage-ag.sgml,v 2.24 2002/11/15 03:11:17 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/manage-ag.sgml,v 2.25 2003/03/13 01:30:29 petere Exp $
 -->
 
 <chapter id="managing-databases">
@@ -16,7 +16,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/manage-ag.sgml,v 2.24 2002/11/15 03:11:17 m
   them.
  </para>
 
- <sect1>
+ <sect1 id="manage-ag-overview">
   <title>Overview</title>
 
   <para>
@@ -24,8 +24,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/manage-ag.sgml,v 2.24 2002/11/15 03:11:17 m
    (<quote>database objects</quote>).  Generally, every database
    object (tables, functions, etc.) belongs to one and only one
    database.  (But there are a few system catalogs, for example
-   <literal>pg_database</>, that belong to a whole installation and
-   are accessible from each database within the installation.)  More
+   <literal>pg_database</>, that belong to a whole cluster and
+   are accessible from each database within the cluster.)  More
    accurately, a database is a collection of schemas and the schemas
    contain the tables, functions, etc.  So the full hierarchy is:
    server, database, schema, table (or something else instead of a
@@ -70,10 +70,10 @@ $Header: /cvsroot/pgsql/doc/src/sgml/manage-ag.sgml,v 2.24 2002/11/15 03:11:17 m
   </para>
 
   <para>
-   Databases are created with the query language command
+   Databases are created with the SQL command
    <command>CREATE DATABASE</command>:
 <synopsis>
-CREATE DATABASE <replaceable>name</>
+CREATE DATABASE <replaceable>name</>;
 </synopsis>
    where <replaceable>name</> follows the usual rules for
    <acronym>SQL</acronym> identifiers.  The current user automatically
@@ -93,14 +93,14 @@ CREATE DATABASE <replaceable>name</>
    question remains how the <emphasis>first</> database at any given
    site can be created. The first database is always created by the
    <command>initdb</> command when the data storage area is
-   initialized. (See <xref linkend="creating-cluster">.) By convention
-   this database is called <literal>template1</>. So to create the
+   initialized. (See <xref linkend="creating-cluster">.)
+   This database is called <literal>template1</>. So to create the
    first <quote>real</> database you can connect to
    <literal>template1</>.
   </para>
 
   <para>
-   The name <quote>template1</quote> is no accident: When a new
+   The name <literal>template1</literal> is no accident: When a new
    database is created, the template database is essentially cloned.
    This means that any changes you make in <literal>template1</> are
    propagated to all subsequently created databases. This implies that
@@ -118,9 +118,9 @@ CREATE DATABASE <replaceable>name</>
 createdb <replaceable class="parameter">dbname</replaceable>
 </synopsis>
 
-   <command>createdb</> does no magic. It connects to the template1
+   <command>createdb</> does no magic. It connects to the <literal>template1</>
    database and issues the <command>CREATE DATABASE</> command,
-   exactly as described above. It uses the <application>psql</> program
+   exactly as described above. It uses the <command>psql</> program
    internally. The reference page on <command>createdb</> contains the invocation
    details. Note that <command>createdb</> without any arguments will create
    a database with the current user name, which may or may not be what
@@ -174,7 +174,7 @@ createdb -O <replaceable>username</> <replaceable>dbname</>
    <literal>template1</>, that is, only the standard objects predefined by
    your version of <productname>PostgreSQL</productname>.
      <literal>template0</> should never be changed 
-   after <literal>initdb</>.  By instructing <command>CREATE DATABASE</> to
+   after <command>initdb</>.  By instructing <command>CREATE DATABASE</> to
    copy <literal>template0</> instead of <literal>template1</>, you can
    create a <quote>virgin</> user database that contains none of the
    site-local additions in <literal>template1</>.  This is particularly
@@ -198,7 +198,7 @@ createdb -T template0 <replaceable>dbname</>
 
   <para>
    It is possible to create additional template databases, and indeed
-   one might copy any database in an installation by specifying its name
+   one might copy any database in a cluster by specifying its name
    as the template for <command>CREATE DATABASE</>.  It is important to
    understand, however, that this is not (yet) intended as
    a general-purpose <quote><command>COPY DATABASE</command></quote> facility.  In particular, it is
@@ -206,7 +206,7 @@ createdb -T template0 <replaceable>dbname</>
    in progress)
    for the duration of the copying operation.  <command>CREATE DATABASE</>
    will check
-   that no backend processes (other than itself) are connected to
+   that no session (other than itself) is connected to
    the source database at the start of the operation, but this does not
    guarantee that changes cannot be made while the copy proceeds, which
    would result in an inconsistent copied database.  Therefore,
@@ -225,11 +225,9 @@ createdb -T template0 <replaceable>dbname</>
    If <literal>datallowconn</literal> is false, then no new connections
    to that database will be allowed (but existing sessions are not killed
    simply by setting the flag false).  The <literal>template0</literal>
-   database is normally marked <literal>datallowconn</literal> =
-   <literal>false</> to prevent modification of it.
+   database is normally marked <literal>datallowconn = false</> to prevent modification of it.
    Both <literal>template0</literal> and <literal>template1</literal>
-   should always be marked with <literal>datistemplate</literal> =
-   <literal>true</>.
+   should always be marked with <literal>datistemplate = true</>.
   </para>
 
   <para>
@@ -237,11 +235,11 @@ createdb -T template0 <replaceable>dbname</>
    it is a good idea to perform
    <command>VACUUM FREEZE</> or <command>VACUUM FULL FREEZE</> in that
    database.  If this is done when there are no other open transactions
-   in the same database, then it is guaranteed that all tuples in the
+   in the same database, then it is guaranteed that all rows in the
    database are <quote>frozen</> and will not be subject to transaction
    ID wraparound problems.  This is particularly important for a database
    that will have <literal>datallowconn</literal> set to false, since it
-   will be impossible to do routine maintenance <command>VACUUM</>s on
+   will be impossible to do routine maintenance <command>VACUUM</> in
    such a database.
    See <xref linkend="vacuum-for-wraparound"> for more information.
   </para>
@@ -295,7 +293,7 @@ ALTER DATABASE mydb SET geqo TO off;
 
    <para>
     It is possible to create a database in a location other than the
-    default location for the installation. Remember that all database access
+    default location for the installation. But remember that all database access
     occurs through the 
     database server, so any location specified must be
     accessible by the server.
@@ -317,7 +315,7 @@ ALTER DATABASE mydb SET geqo TO off;
    <para>
     To create the variable in the environment of the server process
     you must first shut down the server, define the variable,
-    initialize the data area, and finally restart the server. (See
+    initialize the data area, and finally restart the server. (See also
     <xref linkend="postmaster-shutdown"> and <xref
     linkend="postmaster-start">.) To set an environment variable, type
 <programlisting>
@@ -328,7 +326,7 @@ export PGDATA2
 <programlisting>
 setenv PGDATA2 /home/postgres/data
 </programlisting>
-    in <application>csh</> or <application>tcsh</>. You have to make sure that this environment
+    in <command>csh</> or <command>tcsh</>. You have to make sure that this environment
     variable is always defined in the server environment, otherwise
     you won't be able to access that database. Therefore you probably
     want to set it in some sort of shell start-up file or server
@@ -352,7 +350,7 @@ initlocation PGDATA2
    <para>
     To create a database within the new location, use the command
 <synopsis>
-CREATE DATABASE <replaceable>name</> WITH LOCATION = '<replaceable>location</>'
+CREATE DATABASE <replaceable>name</> WITH LOCATION '<replaceable>location</>';
 </synopsis>
     where <replaceable>location</> is the environment variable you
     used, <envar>PGDATA2</> in this example. The <command>createdb</>
@@ -386,9 +384,9 @@ gmake CPPFLAGS=-DALLOW_ABSOLUTE_DBPATHS all
   <para>
    Databases are destroyed with the command <command>DROP DATABASE</command>:
 <synopsis>
-DROP DATABASE <replaceable>name</>
+DROP DATABASE <replaceable>name</>;
 </synopsis>
-   Only the owner of the database (i.e., the user that created it), or
+   Only the owner of the database (i.e., the user that created it) or
    a superuser, can drop a database. Dropping a database removes all objects
    that were 
    contained within the database. The destruction of a database cannot
@@ -399,8 +397,8 @@ DROP DATABASE <replaceable>name</>
    You cannot execute the <command>DROP DATABASE</command> command
    while connected to the victim database. You can, however, be
    connected to any other database, including the <literal>template1</>
-   database, 
-   which would be the only option for dropping the last user database of a
+   database.
+   <literal>template1</> would be the only option for dropping the last user database of a
    given cluster.
   </para>
 

doc/src/sgml/queries.sgml

-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/queries.sgml,v 1.19 2002/11/11 20:14:03 petere Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/queries.sgml,v 1.20 2003/03/13 01:30:29 petere Exp $ -->
 
 <chapter id="queries">
  <title>Queries</title>
@@ -157,18 +157,17 @@ FROM <replaceable>table_reference</replaceable> <optional>, <replaceable>table_r
         row consisting of all columns in <replaceable>T1</replaceable>
         followed by all columns in <replaceable>T2</replaceable>.  If
         the tables have N and M rows respectively, the joined
-        table will have N * M rows.  A cross join is equivalent to an
-        <literal>INNER JOIN ON TRUE</literal>.
+        table will have N * M rows.
        </para>
 
-       <tip>
-        <para>
-         <literal>FROM <replaceable>T1</replaceable> CROSS JOIN
-         <replaceable>T2</replaceable></literal> is equivalent to
-         <literal>FROM <replaceable>T1</replaceable>,
-         <replaceable>T2</replaceable></literal>.
-        </para>
-       </tip>
+       <para>
+        <literal>FROM <replaceable>T1</replaceable> CROSS JOIN
+        <replaceable>T2</replaceable></literal> is equivalent to
+        <literal>FROM <replaceable>T1</replaceable>,
+        <replaceable>T2</replaceable></literal>.  It is also equivalent to
+        <literal>FROM <replaceable>T1</replaceable> INNER JOIN
+        <replaceable>T2</replaceable> ON TRUE</literal> (see below).
+       </para>
       </listitem>
      </varlistentry>
 
@@ -240,7 +239,6 @@ FROM <replaceable>table_reference</replaceable> <optional>, <replaceable>table_r
 
        <para>
         The possible types of qualified join are:
-       </para>
 
        <variablelist>
         <varlistentry>
@@ -302,6 +300,7 @@ FROM <replaceable>table_reference</replaceable> <optional>, <replaceable>table_r
          </listitem>
         </varlistentry>
        </variablelist>
+       </para>
       </listitem>
      </varlistentry>
     </variablelist>
@@ -630,12 +629,12 @@ SELECT ... FROM fdt WHERE EXISTS (SELECT c1 FROM t2 WHERE c2 > fdt.c1)
     condition of the <literal>WHERE</> clause are eliminated from
     <literal>fdt</literal>. Notice the use of scalar subqueries as
     value expressions.  Just like any other query, the subqueries can
-    employ complex table expressions.  Notice how
+    employ complex table expressions.  Notice also how
     <literal>fdt</literal> is referenced in the subqueries.
     Qualifying <literal>c1</> as <literal>fdt.c1</> is only necessary
     if <literal>c1</> is also the name of a column in the derived
-    input table of the subquery.  Qualifying the column name adds
-    clarity even when it is not needed.  This shows how the column
+    input table of the subquery.  But qualifying the column name adds
+    clarity even when it is not needed.  This example shows how the column
     naming scope of an outer query extends into its inner queries.
    </para>
   </sect2>
@@ -663,7 +662,7 @@ SELECT <replaceable>select_list</replaceable>
 </synopsis>
 
    <para>
-    The <literal>GROUP BY</> clause is used to group together rows in
+    The <literal>GROUP BY</> clause is used to group together those rows in
     a table that share the same values in all the columns listed. The
     order in which the columns are listed does not matter.  The
     purpose is to reduce each group of rows sharing common values into
@@ -711,7 +710,7 @@ SELECT <replaceable>select_list</replaceable>
  c |   2
 (3 rows)
 </screen>
-    Here <literal>sum()</literal> is an aggregate function that
+    Here <literal>sum</literal> is an aggregate function that
     computes a single value over the entire group.  More information
     about the available aggregate functions can be found in <xref
     linkend="functions-aggregate">.
@@ -727,9 +726,8 @@ SELECT <replaceable>select_list</replaceable>
    </tip>
 
    <para>
-    Here is another example:  <function>sum(sales)</function> on a
-    table grouped by product code gives the total sales for each
-    product, not the total sales on all products.
+    Here is another example:  it calculates the total sales for each
+    product (rather than the total sales on all products).
 <programlisting>
 SELECT product_id, p.name, (sum(s.units) * p.price) AS sales
     FROM products p LEFT JOIN sales s USING (product_id)
@@ -744,8 +742,8 @@ SELECT product_id, p.name, (sum(s.units) * p.price) AS sales
     unnecessary, but this is not implemented yet.)  The column
     <literal>s.units</> does not have to be in the <literal>GROUP
     BY</> list since it is only used in an aggregate expression
-    (<function>sum()</function>), which represents the group of sales
-    of a product.  For each product, a summary row is returned about
+    (<literal>sum(...)</literal>), which represents the sales
+    of a product.  For each product, the query returns a summary row about
     all sales of the product.
    </para>
 
@@ -800,10 +798,11 @@ SELECT product_id, p.name, (sum(s.units) * (p.price - p.cost)) AS profit
     HAVING sum(p.price * s.units) > 5000;
 </programlisting>
     In the example above, the <literal>WHERE</> clause is selecting
-    rows by a column that is not grouped, while the <literal>HAVING</>
+    rows by a column that is not grouped (the expression is only true for
+    sales during the last four weeks), while the <literal>HAVING</>
     clause restricts the output to groups with total gross sales over
     5000.  Note that the aggregate expressions do not necessarily need
-    to be the same everywhere.
+    to be the same in all parts of the query.
    </para>
   </sect2>
  </sect1>
@@ -852,7 +851,7 @@ SELECT a, b, c FROM ...
     If more than one table has a column of the same name, the table
     name must also be given, as in
 <programlisting>
-SELECT tbl1.a, tbl2.b, tbl1.c FROM ...
+SELECT tbl1.a, tbl2.a, tbl1.b FROM ...
 </programlisting>
     (See also <xref linkend="queries-where">.)
    </para>
@@ -860,7 +859,7 @@ SELECT tbl1.a, tbl2.b, tbl1.c FROM ...
    <para>
     If an arbitrary value expression is used in the select list, it
     conceptually adds a new virtual column to the returned table.  The
-    value expression is evaluated once for each retrieved row, with
+    value expression is evaluated once for each result row, with
     the row's values substituted for any column references.  But the
     expressions in the select list do not have to reference any
     columns in the table expression of the <literal>FROM</> clause;
@@ -888,7 +887,7 @@ SELECT a AS value, b + c AS sum FROM ...
    </para>
 
    <para>
-    If no output column name is specified via AS, the system assigns a
+    If no output column name is specified using <literal>AS</>, the system assigns a
     default name.  For simple column references, this is the name of the
     referenced column.  For function 
     calls, this is the name of the function.  For complex expressions,
@@ -1129,7 +1128,7 @@ SELECT <replaceable>select_list</replaceable>
 
   <para>
    <literal>OFFSET</> says to skip that many rows before beginning to
-   return rows to the client.  <literal>OFFSET 0</> is the same as
+   return rows.  <literal>OFFSET 0</> is the same as
    omitting the <literal>OFFSET</> clause.  If both <literal>OFFSET</>
    and <literal>LIMIT</> appear, then <literal>OFFSET</> rows are
    skipped before starting to count the <literal>LIMIT</> rows that
@@ -1140,7 +1139,7 @@ SELECT <replaceable>select_list</replaceable>
    When using <literal>LIMIT</>, it is a good idea to use an
    <literal>ORDER BY</> clause that constrains the result rows into a
    unique order.  Otherwise you will get an unpredictable subset of
-   the query's rows---you may be asking for the tenth through
+   the query's rows. --- You may be asking for the tenth through
    twentieth rows, but tenth through twentieth in what ordering?  The
    ordering is unknown, unless you specified <literal>ORDER BY</>.
   </para>