Some small docs improvements motivated by reading the comments for the

7.4 interactive docs.

doc/src/sgml/ddl.sgml

@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/ddl.sgml,v 1.35 2004/12/23 05:37:39 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/ddl.sgml,v 1.36 2005/01/08 01:44:05 tgl Exp $ -->
 
 <chapter id="ddl">
  <title>Data Definition</title>
@@ -395,7 +395,28 @@ CREATE TABLE products (
    evaluated whenever the default value is inserted
    (<emphasis>not</emphasis> when the table is created).  A common example
    is that a timestamp column may have a default of <literal>now()</>,
-   so that it gets set to the time of row insertion.
+   so that it gets set to the time of row insertion.  Another common
+   example is generating a <quote>serial number</> for each row.
+   In <productname>PostgreSQL</productname> this is typically done by
+   something like
+<programlisting>
+CREATE TABLE products (
+    product_no integer <emphasis>DEFAULT nextval('products_product_no_seq')</emphasis>,
+    ...
+);
+</programlisting>
+   where the <literal>nextval()</> function supplies successive values
+   from a <firstterm>sequence object</> (see <xref
+   linkend="functions-sequence">). This arrangement is sufficiently common
+   that there's a special shorthand for it:
+<programlisting>
+CREATE TABLE products (
+    product_no <emphasis>SERIAL</emphasis>,
+    ...
+);
+</programlisting>
+   The <literal>SERIAL</> shorthand is discussed further in <xref
+   linkend="datatype-serial">.
   </para>
  </sect1>
 
@@ -1138,6 +1159,12 @@ WHERE c.altitude &gt; 500 and c.tableoid = p.oid;
    
   </para>
 
+  <para>
+   A table can inherit from more than one parent table, in which case it has
+   the union of the columns defined by the parent tables (plus any columns
+   declared specifically for the child table).
+  </para>
+
   <para>
    A serious limitation of the inheritance feature is that indexes (including
    unique constraints) and foreign key constraints only apply to single

doc/src/sgml/history.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/history.sgml,v 1.23 2003/11/29 19:51:37 pgsql Exp $
+$PostgreSQL: pgsql/doc/src/sgml/history.sgml,v 1.24 2005/01/08 01:44:05 tgl Exp $
 -->
 
 <sect1 id="history">
@@ -128,10 +128,11 @@ $PostgreSQL: pgsql/doc/src/sgml/history.sgml,v 1.23 2003/11/29 19:51:37 pgsql Ex
 
     <listitem>
      <para>
-      In addition to the monitor program, a new program
+      A new program
       (<application>psql</application>) was provided for interactive
       SQL queries, which used <acronym>GNU</acronym>
-      <application>Readline</application>.
+      <application>Readline</application>.  This largely superseded
+      the old <application>monitor</> program.
      </para>
     </listitem>
 

doc/src/sgml/query.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/query.sgml,v 1.41 2004/12/17 04:50:32 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/query.sgml,v 1.42 2005/01/08 01:44:08 tgl Exp $
 -->
 
  <chapter id="tutorial-sql">
@@ -293,7 +293,7 @@ COPY weather FROM '/home/user/weather.txt';
 <programlisting>
 SELECT * FROM weather;
 </programlisting>
-    (here <literal>*</literal> means <quote>all columns</quote>).
+    Here <literal>*</literal> is a shorthand for <quote>all columns</quote>.
      <footnote>
       <para>
        While <literal>SELECT *</literal> is useful for off-the-cuff
@@ -301,6 +301,11 @@ SELECT * FROM weather;
        since adding a column to the table would change the results.
       </para>
      </footnote>
+    So the same result would be had with:
+<programlisting>
+SELECT city, temp_lo, temp_hi, prcp, date FROM weather;
+</programlisting>
+
     The output should be:
 
 <screen>
@@ -314,8 +319,8 @@ SELECT * FROM weather;
    </para>
 
    <para>
-    You may specify any arbitrary expressions in the select list.  For 
+    You can write expressions, not just simple column references, in the
-    example, you can do:
+    select list.  For example, you can do:
 <programlisting>
 SELECT city, (temp_hi+temp_lo)/2 AS temp_avg, date FROM weather;
 </programlisting>
@@ -333,15 +338,18 @@ SELECT city, (temp_hi+temp_lo)/2 AS temp_avg, date FROM weather;
    </para>
 
    <para>
-    Arbitrary Boolean operators (<literal>AND</literal>,
+    A query can be <quote>qualified</> by adding a <literal>WHERE</>
+    clause that specifies which rows are wanted.  The <literal>WHERE</>
+    clause contains a Boolean (truth value) expression, and only rows for
+    which the Boolean expression is true are returned.  The usual
+    Boolean operators (<literal>AND</literal>,
     <literal>OR</literal>, and <literal>NOT</literal>) are allowed in
-    the qualification of a query.  For example, the following
+    the qualification.  For example, the following
     retrieves the weather of San Francisco on rainy days:
 
 <programlisting>
 SELECT * FROM weather
-    WHERE city = 'San Francisco'
+    WHERE city = 'San Francisco' AND prcp &gt; 0.0;
-    AND prcp > 0.0;
 </programlisting>
     Result:
 <screen>
@@ -354,16 +362,43 @@ SELECT * FROM weather
 
    <para>
     <indexterm><primary>ORDER BY</primary></indexterm>
+
+    You can request that the results of a query
+    be returned in sorted order:
+
+<programlisting>
+SELECT * FROM weather
+    ORDER BY city;
+</programlisting>
+
+<screen>
+     city      | temp_lo | temp_hi | prcp |    date
+---------------+---------+---------+------+------------
+ Hayward       |      37 |      54 |      | 1994-11-29
+ San Francisco |      43 |      57 |    0 | 1994-11-29
+ San Francisco |      46 |      50 | 0.25 | 1994-11-27
+</screen>
+
+    In this example, the sort order isn't fully specified, and so you
+    might get the San Francisco rows in either order.  But you'd always
+    get the results shown above if you do
+
+<programlisting>
+SELECT * FROM weather
+    ORDER BY city, temp_lo;
+</programlisting>
+   </para>
+
+   <para>
     <indexterm><primary>DISTINCT</primary></indexterm>
     <indexterm><primary>duplicate</primary></indexterm>
 
-    As a final note, you can request that the results of a query can
+    You can request that duplicate rows be removed from the result of
-    be returned in sorted order or with duplicate rows removed:
+    a query:
 
 <programlisting>
 SELECT DISTINCT city
-    FROM weather
+    FROM weather;
-    ORDER BY city;
 </programlisting>
 
 <screen>
@@ -374,8 +409,26 @@ SELECT DISTINCT city
 (2 rows)
 </screen>
 
-    <literal>DISTINCT</literal> and <literal>ORDER BY</literal> can be
+    Here again, the result row ordering might vary.
-    used separately, of course.
+    You can ensure consistent results by using <literal>DISTINCT</literal> and
+    <literal>ORDER BY</literal> together:
+     <footnote>
+      <para>
+       In some database systems, including older versions of
+       <productname>PostgreSQL</productname>, the implementation of
+       <literal>DISTINCT</literal> automatically orders the rows and
+       so <literal>ORDER BY</literal> is redundant.  But this is not
+       required by the SQL standard, and current
+       <productname>PostgreSQL</productname> doesn't guarantee that
+       <literal>DISTINCT</literal> causes the rows to be ordered.
+      </para>
+     </footnote>
+
+<programlisting>
+SELECT DISTINCT city
+    FROM weather
+    ORDER BY city;
+</programlisting>
    </para>
   </sect1>
 

doc/src/sgml/start.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/start.sgml,v 1.37 2004/12/17 04:50:32 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/start.sgml,v 1.38 2005/01/08 01:44:08 tgl Exp $
 -->
 
  <chapter id="tutorial-start">
@@ -146,7 +146,7 @@ $PostgreSQL: pgsql/doc/src/sgml/start.sgml,v 1.37 2004/12/17 04:50:32 tgl Exp $
    <para>
     Possibly, your site administrator has already created a database
     for your use.  He should have told you what the name of your
-    database is.  In this case you can omit this step and skip ahead
+    database is.  In that case you can omit this step and skip ahead
     to the next section.
    </para>
 
@@ -194,8 +194,28 @@ No such file or directory
    </para>
 
    <para>
-    If you do not have the privileges required to create a database,
+    Another response could be this:
-    you will see the following:
+<screen>
+createdb: could not connect to database template1: FATAL:  user "joe" does not
+exist
+</screen>
+    where your own login name is mentioned.  This will happen if the
+    administrator has not created a <productname>PostgreSQL</> user account
+    for you.  (<productname>PostgreSQL</> user accounts are distinct from
+    operating system user accounts.)  If you are the administrator, see
+    <xref linkend="user-manag"> for help creating accounts.  You will need to
+    become the operating system user under which <productname>PostgreSQL</>
+    was installed (usually <literal>postgres</>) to create the first user
+    account.  It could also be that you were assigned a
+    <productname>PostgreSQL</> user name that is different from your
+    operating system user name; in that case you need to use the <option>-U</>
+    switch or set the <envar>PGUSER</> environment variable to specify your
+    <productname>PostgreSQL</> user name.
+   </para>
+
+   <para>
+    If you have a user account but it does not have the privileges required to
+    create a database, you will see the following:
 <screen>
 createdb: database creation failed: ERROR:  permission denied to create database
 </screen>
@@ -340,10 +360,10 @@ mydb=#
    </para>
 
    <para>
-    If you have encountered problems starting <command>psql</command>
+    If you encounter problems starting <command>psql</command>
     then go back to the previous section.  The diagnostics of
-    <command>psql</command> and <command>createdb</command> are
+    <command>createdb</command> and <command>psql</command> are
-    similar, and if the latter worked the former should work as well.
+    similar, and if the former worked the latter should work as well.
    </para>
 
    <para>