Some small docs improvements motivated by reading the comments for the

7.4 interactive docs.

4 files changed, 127 insertions, 26 deletions

diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index 2504970a7e3..6d29859ed97 100644
--- a/doc/src/sgml/ddl.sgml
+++ b/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>
 
@@ -1139,6 +1160,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
    tables, not to their inheritance children.  This is true on both the
diff --git a/doc/src/sgml/history.sgml b/doc/src/sgml/history.sgml
index 5247cf3dc7f..be84418c7df 100644
--- a/doc/src/sgml/history.sgml
+++ b/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>
 
diff --git a/doc/src/sgml/query.sgml b/doc/src/sgml/query.sgml
index 33294afd3c5..7478b4251f1 100644
--- a/doc/src/sgml/query.sgml
+++ b/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 
-    example, you can do:
+    You can write expressions, not just simple column references, in the
+    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'
-    AND prcp > 0.0;
+    WHERE city = 'San Francisco' AND prcp &gt; 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
-    be returned in sorted order or with duplicate rows removed:
+    You can request that duplicate rows be removed from the result of
+    a query:
 
 <programlisting>
 SELECT DISTINCT city
-    FROM weather
-    ORDER BY city;
+    FROM weather;
 </programlisting>
 
 <screen>
@@ -374,8 +409,26 @@ SELECT DISTINCT city
 (2 rows)
 </screen>
 
-    <literal>DISTINCT</literal> and <literal>ORDER BY</literal> can be
-    used separately, of course.
+    Here again, the result row ordering might vary.
+    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>
 
diff --git a/doc/src/sgml/start.sgml b/doc/src/sgml/start.sgml
index c40f76c8ce3..3ae094b37c0 100644
--- a/doc/src/sgml/start.sgml
+++ b/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,
-    you will see the following:
+    Another response could be this:
+<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
-    similar, and if the latter worked the former should work as well.
+    <command>createdb</command> and <command>psql</command> are
+    similar, and if the former worked the latter should work as well.
    </para>
 
    <para>