A small pass of docs review and copy-editing.

doc/src/sgml/array.sgml

@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/array.sgml,v 1.41 2004/12/13 18:05:07 petere Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/array.sgml,v 1.42 2004/12/23 05:37:39 tgl Exp $ -->
 
 <sect1 id="arrays">
  <title>Arrays</title>
@@ -546,11 +546,11 @@ SELECT * FROM sal_emp WHERE 10000 = ALL (pay_by_quarter);
    set to one. If any of an array's dimensions has a lower bound index not
    equal to one, an additional decoration that indicates the actual
    array dimensions will precede the array structure decoration.
-   The decoration consists of square braces (<literal>[</> and <literal>]</>)
+   This decoration consists of square brackets (<literal>[]</>)
-   around each array dimension's lower and upper bound indices, plus
+   around each array dimension's lower and upper bounds, with
-   a colon (<literal>:</>) delimiter character in between. Delimiting the
+   a colon (<literal>:</>) delimiter character in between. The
-   array dimension decoration from the array structure decoration is a
+   array dimension decoration is followed by an equal sign (<literal>=</>).
-   single assignment operator (<literal>=</>). For example:
+   For example:
 <programlisting>
 SELECT 1 || ARRAY[2,3] AS array;
 
@@ -569,8 +569,8 @@ SELECT ARRAY[1,2] || ARRAY[[3,4]] AS array;
   </para>
 
   <para>
-   In a similar fashion, an array with non-default indices may be specified
+   This syntax can also be used to specify non-default array subscripts
-   using the same literal syntax. For example:
+   in an array literal. For example:
 <programlisting>
 SELECT f1[1][-2][3] AS e1, f1[1][-1][5] AS e2
  FROM (SELECT '[1:1][-2:-1][3:5]={{{1,2,3},{4,5,6}}}'::int[] AS f1) AS ss;
@@ -598,8 +598,8 @@ SELECT f1[1][-2][3] AS e1, f1[1][-1][5] AS e2
    You may write whitespace before a left brace or after a right
    brace. You may also write whitespace before or after any individual item
    string. In all of these cases the whitespace will be ignored. However,
-   whitespace within double quoted elements, or surrounded on both sides by
+   whitespace within double-quoted elements, or surrounded on both sides by
-   non-whitespace characters of an element, are not ignored.
+   non-whitespace characters of an element, is not ignored.
   </para>
 
  <note>
@@ -618,6 +618,8 @@ INSERT ... VALUES ('{"\\\\","\\""}');
    with a data type whose input routine also treated backslashes specially,
    <type>bytea</> for example, we might need as many as eight backslashes
    in the command to get one backslash into the stored array element.)
+   Dollar quoting (see <xref linkend="sql-syntax-dollar-quoting">) may be
+   used to avoid the need to double backslashes.
   </para>
  </note>
 

doc/src/sgml/datatype.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.151 2004/11/27 21:27:05 petere Exp $
+$PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.152 2004/12/23 05:37:39 tgl Exp $
 -->
 
  <chapter id="datatype">
@@ -22,9 +22,8 @@ $PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.151 2004/11/27 21:27:05 petere
   </para>
 
   <para>
-   <xref linkend="datatype-table"> shows all built-in general-purpose data types.
+   <xref linkend="datatype-table"> shows all the built-in general-purpose data
-   Most of the alternative names
+   types. Most of the alternative names listed in the 
-   listed in the 
    <quote>Aliases</quote> column are the names used internally by
    <productname>PostgreSQL</productname> for historical reasons.  In
    addition, some internally used or deprecated types are available,
@@ -82,7 +81,7 @@ $PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.151 2004/11/27 21:27:05 petere
       <row>
        <entry><type>bytea</type></entry>
        <entry></entry>
-       <entry>binary data</entry>
+       <entry>binary data (<quote>byte array</>)</entry>
       </row>
 
       <row>
@@ -142,7 +141,7 @@ $PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.151 2004/11/27 21:27:05 petere
       <row>
        <entry><type>line</type></entry>
        <entry></entry>
-       <entry>infinite line in the plane (not fully implemented)</entry>
+       <entry>infinite line in the plane</entry>
       </row>
 
       <row>
@@ -168,13 +167,13 @@ $PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.151 2004/11/27 21:27:05 petere
          <replaceable>s</replaceable>) ]</type></entry>
        <entry><type>decimal [ (<replaceable>p</replaceable>,
          <replaceable>s</replaceable>) ]</type></entry>
-       <entry>exact numeric with selectable precision</entry>
+       <entry>exact numeric of selectable precision</entry>
       </row>
 
       <row>
        <entry><type>path</type></entry>
        <entry></entry>
-       <entry>open or closed geometric path in the plane</entry>
+       <entry>geometric path in the plane</entry>
       </row>
 
       <row>
@@ -227,7 +226,7 @@ $PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.151 2004/11/27 21:27:05 petere
 
       <row>
        <entry><type>timestamp [ (<replaceable>p</replaceable>) ] [ without time zone ]</type></entry>
-       <entry><type></type></entry>
+       <entry></entry>
        <entry>date and time</entry>
       </row>
 
@@ -259,7 +258,7 @@ $PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.151 2004/11/27 21:27:05 petere
    Each data type has an external representation determined by its input
    and output functions.  Many of the built-in types have
    obvious external formats.  However, several types are either unique
-   to <productname>PostgreSQL</productname>, such as open and closed
+   to <productname>PostgreSQL</productname>, such as geometric
    paths, or have several possibilities for formats, such as the date
    and time types.
    Some of the input and output functions are not invertible.  That is,
@@ -267,14 +266,6 @@ $PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.151 2004/11/27 21:27:05 petere
    the original input.
   </para>
 
-  <para>
-   Some of the operators and functions (e.g.,
-   addition and multiplication) do not perform run-time error-checking in the
-   interests of improving execution speed.
-   On some systems, for example, the numeric operators for some data types may
-   silently cause underflow or overflow.
-  </para>
-
   <sect1 id="datatype-numeric">
    <title>Numeric Types</title>
 
@@ -285,7 +276,7 @@ $PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.151 2004/11/27 21:27:05 petere
 
    <para>
     Numeric types consist of two-, four-, and eight-byte integers,
-    four- and eight-byte floating-point numbers, and fixed-precision
+    four- and eight-byte floating-point numbers, and selectable-precision
     decimals.  <xref linkend="datatype-numeric-table"> lists the
     available types.
    </para>
@@ -755,7 +746,7 @@ CREATE TABLE <replaceable class="parameter">tablename</replaceable> (
      created by reloading a dump from a pre-7.3 database; the dump
      file does not contain the information needed to establish the
      dependency link.) Furthermore, this dependency between sequence
-     and column is made only for the <type>serial</> column itself; if
+     and column is made only for the <type>serial</> column itself. If
      any other columns reference the sequence (perhaps by manually
      calling the <function>nextval</> function), they will be broken
      if the sequence is removed. Using a <type>serial</> column's sequence
@@ -916,7 +907,7 @@ CREATE TABLE <replaceable class="parameter">tablename</replaceable> (
     varying(<replaceable>n</>)</type> and
     <type>character(<replaceable>n</>)</type>, respectively.
     <type>character</type> without length specifier is equivalent to
-    <type>character(1)</type>; if <type>character varying</type> is used
+    <type>character(1)</type>. If <type>character varying</type> is used
     without length specifier, the type accepts strings of any size. The
     latter is a <productname>PostgreSQL</> extension.
    </para>
@@ -1114,8 +1105,8 @@ SELECT b, char_length(b) FROM test2;
     literal in an <acronym>SQL</acronym> statement. In general, to
     escape an octet, it is converted into the three-digit octal number
     equivalent of its decimal octet value, and preceded by two
-    backslashes. <xref linkend="datatype-binary-sqlesc"> contains the
+    backslashes. <xref linkend="datatype-binary-sqlesc"> shows the
-    characters which must be escaped, and gives the alternate escape
+    characters that must be escaped, and gives the alternate escape
     sequences where applicable.
    </para>
 
@@ -2429,7 +2420,7 @@ SELECT * FROM test1 WHERE a;
     <para>
      Boxes are represented by pairs of points that are opposite
      corners of the box.
-     Values of type <type>box</type> is specified using the following syntax:
+     Values of type <type>box</type> are specified using the following syntax:
 
 <synopsis>
 ( ( <replaceable>x1</replaceable> , <replaceable>y1</replaceable> ) , ( <replaceable>x2</replaceable> , <replaceable>y2</replaceable> ) )
@@ -2441,7 +2432,7 @@ SELECT * FROM test1 WHERE a;
      <literal>(<replaceable>x1</replaceable>,<replaceable>y1</replaceable>)</literal>
      and
      <literal>(<replaceable>x2</replaceable>,<replaceable>y2</replaceable>)</literal>
-     are the opposite corners of the box.
+     are any two opposite corners of the box.
     </para>
 
     <para>
@@ -2449,7 +2440,7 @@ SELECT * FROM test1 WHERE a;
      The corners are reordered on input to store
      the upper right corner, then the lower left corner.
      Other corners of the box can be entered, but the lower
-     left and upper right corners are determined from the input and stored corners.
+     left and upper right corners are determined from the input and stored.
     </para>
    </sect2>
 
@@ -2461,18 +2452,11 @@ SELECT * FROM test1 WHERE a;
     </indexterm>
 
     <para>
-     Paths are represented by connected sets of points. Paths can be
+     Paths are represented by lists of connected points. Paths can be
      <firstterm>open</firstterm>, where
-     the first and last points in the set are not connected, and <firstterm>closed</firstterm>,
+     the first and last points in the list are not connected, or
-     where the first and last point are connected. The functions
+     <firstterm>closed</firstterm>,
-     <function>popen(<replaceable>p</>)</function>
+     where the first and last points are connected.
-     and
-     <function>pclose(<replaceable>p</>)</function>
-     are supplied to force a path to be open or closed, and the functions
-     <function>isopen(<replaceable>p</>)</function>
-     and
-     <function>isclosed(<replaceable>p</>)</function>
-     are supplied to test for either type in an expression.
     </para>
 
     <para>
@@ -2505,7 +2489,8 @@ SELECT * FROM test1 WHERE a;
     </indexterm>
 
     <para>
-     Polygons are represented by sets of points. Polygons should probably be
+     Polygons are represented by lists of points (the vertexes of the
+     polygon). Polygons should probably be
      considered equivalent to closed paths, but are stored differently 
      and have their own set of support routines.
     </para>
@@ -2569,8 +2554,9 @@ SELECT * FROM test1 WHERE a;
 
    <para>
     <productname>PostgreSQL</> offers data types to store IPv4, IPv6, and MAC
-    addresses, shown in <xref linkend="datatype-net-types-table">.  It
+    addresses, as shown in <xref linkend="datatype-net-types-table">.  It
-    is preferable to use these types over plain text types, because
+    is preferable to use these types instead of plain text types to store
+    network addresses, because
     these types offer input error checking and several specialized
     operators and functions.
    </para>
@@ -2590,7 +2576,7 @@ SELECT * FROM test1 WHERE a;
        <row>
         <entry><type>cidr</type></entry>
         <entry>12 or 24 bytes</entry>
-        <entry>IPv4 or IPv6 networks</entry>
+        <entry>IPv4 and IPv6 networks</entry>
        </row>
 
        <row>
@@ -2631,7 +2617,7 @@ SELECT * FROM test1 WHERE a;
      the host address represent the network address (the
      <quote>netmask</quote>).  If the netmask is 32 and the address is IPv4,
      then the value does not indicate a subnet, only a single host.
-     In IPv6, the address length is 128 bits, so 128 bits will specify a
+     In IPv6, the address length is 128 bits, so 128 bits specify a
      unique host address.  Note that if you
      want to accept networks only, you should use the
      <type>cidr</type> type rather than <type>inet</type>.
@@ -2647,7 +2633,7 @@ SELECT * FROM test1 WHERE a;
       is the number of bits in the netmask.  If the
       <replaceable class="parameter">/y</replaceable>
       part is left off, then the
-      netmask is 32 for IPv4 and 128 for IPv6, and the value represents
+      netmask is 32 for IPv4 and 128 for IPv6, so the value represents
       just a single host.  On display, the
       <replaceable class="parameter">/y</replaceable>
       portion is suppressed if the netmask specifies a single host.
@@ -2824,7 +2810,7 @@ SELECT * FROM test1 WHERE a;
      which would all specify the same
      address.  Upper and lower case is accepted for the digits
      <literal>a</> through <literal>f</>.  Output is always in the
-     last of the shown forms.
+     last of the forms shown.
     </para>
 
     <para>

doc/src/sgml/ddl.sgml

@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/ddl.sgml,v 1.34 2004/12/13 18:05:08 petere Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/ddl.sgml,v 1.35 2004/12/23 05:37:39 tgl Exp $ -->
 
 <chapter id="ddl">
  <title>Data Definition</title>
@@ -260,7 +260,7 @@ DROP TABLE products;
      <para>
       The identity (transaction ID) of the deleting transaction, or
       zero for an undeleted row version.  It is possible for this column to
-      be nonzero in a visible row version: That usually indicates that the
+      be nonzero in a visible row version. That usually indicates that the
       deleting transaction hasn't committed yet, or that an attempted
       deletion was rolled back.
      </para>
@@ -329,8 +329,8 @@ DROP TABLE products;
       <para>
        The tables in question should be created using <literal>WITH
        OIDS</literal> to ensure forward compatibility with future
-       releases of <productname>PostgreSQL</productname> in which OIDs
+       releases of <productname>PostgreSQL</productname>.  It is
-       are not included in all tables by default.
+       planned that <literal>WITHOUT OIDS</> will become the default.
       </para>
      </listitem>
     </itemizedlist>
@@ -367,15 +367,15 @@ DROP TABLE products;
    created and no values are specified for some of the columns, the
    columns will be filled with their respective default values.  A
    data manipulation command can also request explicitly that a column
-   be set to its default value, without knowing what this value is.
+   be set to its default value, without having to know what that value is.
    (Details about data manipulation commands are in <xref linkend="dml">.)
   </para>
 
   <para>
    <indexterm><primary>null value</primary><secondary>default value</secondary></indexterm>
-   If no default value is declared explicitly, the null value is the
+   If no default value is declared explicitly, the default value is the
-   default value.  This usually makes sense because a null value can
+   null value.  This usually makes sense because a null value can
-   be thought to represent unknown data.
+   be considered to represent unknown data.
   </para>
 
   <para>
@@ -393,7 +393,9 @@ CREATE TABLE products (
   <para>
    The default value may be a scalar expression, which will be
    evaluated whenever the default value is inserted
-   (<emphasis>not</emphasis> when the table is created).
+   (<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.
   </para>
  </sect1>
 
@@ -544,7 +546,7 @@ CREATE TABLE products (
     expressions will evaluate to the null value if one operand is null,
     they will not prevent null values in the constrained columns.  To
     ensure that a column does not contain null values, the not-null
-    constraint described in the next section should be used.
+    constraint described in the next section can be used.
    </para>
   </sect2>
 
@@ -691,11 +693,11 @@ CREATE TABLE products (
    </indexterm>
 
    <para>
-    In general, a unique constraint is violated when there are (at
+    In general, a unique constraint is violated when there are two or
-    least) two rows in the table where the values of each of the
+    more rows in the table where the values of all of the
-    corresponding columns that are part of the constraint are equal.
+    columns included in the constraint are equal.
     However, null values are not considered equal in this
-    consideration.  That means even in the presence of a
+    comparison.  That means even in the presence of a
     unique constraint it is possible to store an unlimited number of
     rows that contain a null value in at least one of the constrained
     columns.  This behavior conforms to the SQL standard, but we have
@@ -839,7 +841,7 @@ CREATE TABLE orders (
 );
 </programlisting>
     because in absence of a column list the primary key of the
-    referenced table is used as the referenced column.
+    referenced table is used as the referenced column(s).
    </para>
 
    <para>
@@ -902,7 +904,7 @@ CREATE TABLE order_items (
     We know that the foreign keys disallow creation of orders that
     do not relate to any products.  But what if a product is removed
     after an order is created that references it?  SQL allows you to
-    specify that as well.  Intuitively, we have a few options:
+    handle that as well.  Intuitively, we have a few options:
     <itemizedlist spacing="compact">
      <listitem><para>Disallow deleting a referenced product</para></listitem>
      <listitem><para>Delete the orders as well</para></listitem>
@@ -940,13 +942,15 @@ CREATE TABLE order_items (
 
    <para>
     Restricting and cascading deletes are the two most common options.
-    <literal>RESTRICT</literal> prevents a statement from deleting a
+    <literal>RESTRICT</literal> prevents deletion of a
     referenced row. <literal>NO ACTION</literal> means that if any
     referencing rows still exist when the constraint is checked, an error
-    is raised; this is the default if you do not specify anything.
+    is raised; this is the default behavior if you do not specify anything.
-    (The essential difference between these choices is that
+    (The essential difference between these two choices is that
     <literal>NO ACTION</literal> allows the check to be deferred until
     later in the transaction, whereas <literal>RESTRICT</literal> does not.)
+    <literal>CASCADE</> specifies that when a referenced row is deleted,
+    row(s) referencing it should be automatically deleted as well.
     There are two other options:
     <literal>SET NULL</literal> and <literal>SET DEFAULT</literal>.
     These cause the referencing columns to be set to nulls or default
@@ -954,13 +958,13 @@ CREATE TABLE order_items (
     Note that these do not excuse you from observing any constraints.
     For example, if an action specifies <literal>SET DEFAULT</literal>
     but the default value would not satisfy the foreign key, the
-    deletion of the primary key will fail.
+    operation will fail.
    </para>
 
    <para>
     Analogous to <literal>ON DELETE</literal> there is also
-    <literal>ON UPDATE</literal> which is invoked when a primary key
+    <literal>ON UPDATE</literal> which is invoked when a referenced
-    is changed (updated).  The possible actions are the same.
+    column is changed (updated).  The possible actions are the same.
    </para>
 
    <para>
@@ -1219,6 +1223,9 @@ WHERE c.altitude &gt; 500 and c.tableoid = p.oid;
     <listitem>
      <para>Change default values,</para>
     </listitem>
+    <listitem>
+     <para>Change column data types,</para>
+    </listitem>
     <listitem>
      <para>Rename columns,</para>
     </listitem>
@@ -1227,8 +1234,9 @@ WHERE c.altitude &gt; 500 and c.tableoid = p.oid;
     </listitem>
    </itemizedlist>
 
-   All these actions are performed using the <literal>ALTER
+   All these actions are performed using the
-   TABLE</literal> command.
+   <xref linkend="sql-altertable" endterm="sql-altertable-title">
+   command.
   </para>
 
   <sect2>
@@ -1343,7 +1351,7 @@ ALTER TABLE products ALTER COLUMN product_no DROP NOT NULL;
   </sect2>
 
   <sect2>
-   <title>Changing the Default</title>
+   <title>Changing a Column's Default Value</title>
 
    <indexterm>
     <primary>default value</primary>
@@ -1366,6 +1374,35 @@ ALTER TABLE products ALTER COLUMN price DROP DEFAULT;
    </para>
   </sect2>
 
+  <sect2>
+   <title>Changing a Column's Data Type</title>
+
+   <indexterm>
+    <primary>column data type</primary>
+    <secondary>changing</secondary>
+   </indexterm>
+
+   <para>
+    To convert a column to a different data type, use a command like this:
+<programlisting>
+ALTER TABLE products ALTER COLUMN price TYPE numeric(10,2);
+</programlisting>
+    This will succeed only if each existing entry in the column can be
+    converted to the new type by an implicit cast.  If a more complex
+    conversion is needed, you can add a <literal>USING</> clause that
+    specifies how to compute the new values from the old.
+   </para>
+
+   <para>
+    <productname>PostgreSQL</> will attempt to convert the column's
+    default value (if any) to the new type, as well as any constraints
+    that involve the column.  But these conversions may fail, or may
+    produce surprising results.  It's often best to drop any constraints
+    on the column before altering its type, and then add back suitably
+    modified constraints afterwards.
+   </para>
+  </sect2>
+
   <sect2>
    <title>Renaming a Column</title>
 
@@ -1568,7 +1605,7 @@ REVOKE ALL ON accounts FROM PUBLIC;
    </indexterm>
 
    <para>
-    To create a separate schema, use the command <literal>CREATE
+    To create a schema, use the command <literal>CREATE
     SCHEMA</literal>.  Give the schema a name of your choice.  For
     example:
 <programlisting>
@@ -1830,7 +1867,7 @@ REVOKE CREATE ON SCHEMA public FROM PUBLIC;
     (The first <quote>public</quote> is the schema, the second
     <quote>public</quote> means <quote>every user</quote>.  In the
     first sense it is an identifier, in the second sense it is a
-    reserved word, hence the different capitalization; recall the
+    key word, hence the different capitalization; recall the
     guidelines from <xref linkend="sql-syntax-identifiers">.)
    </para>
   </sect2>

doc/src/sgml/dml.sgml

@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/dml.sgml,v 1.8 2003/11/29 19:51:36 pgsql Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/dml.sgml,v 1.9 2004/12/23 05:37:39 tgl Exp $ -->
 
 <chapter id="dml">
  <title>Data Manipulation</title>
@@ -161,7 +161,7 @@ UPDATE products SET price = 10 WHERE price = 5;
   </para>
 
   <para>
-   Let's look at that command in detail: First is the key word
+   Let's look at that command in detail. First is the key word
    <literal>UPDATE</literal> followed by the table name.  As usual,
    the table name may be schema-qualified, otherwise it is looked up
    in the path.  Next is the key word <literal>SET</literal> followed
@@ -172,21 +172,22 @@ UPDATE products SET price = 10 WHERE price = 5;
 <programlisting>
 UPDATE products SET price = price * 1.10;
 </programlisting>
-   As you see, the expression for the new value can also refer to the
+   As you see, the expression for the new value can refer to the existing
-   old value.  We also left out the <literal>WHERE</literal> clause.
+   value(s) in the row.  We also left out the <literal>WHERE</literal> clause.
    If it is omitted, it means that all rows in the table are updated.
-   If it is present, only those rows that match the condition after
+   If it is present, only those rows that match the
-   the <literal>WHERE</literal> are updated.  Note that the equals
+   <literal>WHERE</literal> condition are updated.  Note that the equals
    sign in the <literal>SET</literal> clause is an assignment while
    the one in the <literal>WHERE</literal> clause is a comparison, but
-   this does not create any ambiguity.  Of course, the condition does
+   this does not create any ambiguity.  Of course, the
+   <literal>WHERE</literal> condition does
    not have to be an equality test.  Many other operators are
    available (see <xref linkend="functions">).  But the expression
    needs to evaluate to a Boolean result.
   </para>
 
   <para>
-   You can also update more than one column in an
+   You can update more than one column in an
    <literal>UPDATE</literal> command by listing more than one
    assignment in the <literal>SET</literal> clause.  For example:
 <programlisting>
@@ -211,7 +212,7 @@ UPDATE mytable SET a = 5, b = 3, c = 1 WHERE a > 0;
    change data.  What remains is to discuss how to remove data that is
    no longer needed.  Just as adding data is only possible in whole
    rows, you can only remove entire rows from a table.  In the
-   previous section we discussed that SQL does not provide a way to
+   previous section we explained that SQL does not provide a way to
    directly address individual rows.  Therefore, removing rows can
    only be done by specifying conditions that the rows to be removed
    have to match.  If you have a primary key in the table then you can

doc/src/sgml/intro.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/intro.sgml,v 1.26 2004/11/27 21:27:06 petere Exp $
+$PostgreSQL: pgsql/doc/src/sgml/intro.sgml,v 1.27 2004/12/23 05:37:39 tgl Exp $
 -->
 
 <preface id="preface">
@@ -41,7 +41,7 @@ $PostgreSQL: pgsql/doc/src/sgml/intro.sgml,v 1.26 2004/11/27 21:27:06 petere Exp
    <listitem>
     <para>
      <xref linkend="admin"> describes the installation and
-     administration of the server.  Everyone that runs a
+     administration of the server.  Everyone who runs a
      <productname>PostgreSQL</productname> server, be it for private
      use or for others, should read this part.
     </para>
@@ -67,8 +67,8 @@ $PostgreSQL: pgsql/doc/src/sgml/intro.sgml,v 1.26 2004/11/27 21:27:06 petere Exp
 
    <listitem>
     <para>
-     <xref linkend="reference"> contains information about the syntax
+     <xref linkend="reference"> contains reference information about
-     of SQL commands, client and server programs.  This part supports
+     SQL commands, client and server programs.  This part supports
      the other parts with structured information sorted by command or
      program.
     </para>
@@ -76,7 +76,7 @@ $PostgreSQL: pgsql/doc/src/sgml/intro.sgml,v 1.26 2004/11/27 21:27:06 petere Exp
 
    <listitem>
     <para>
-     <xref linkend="internals"> contains assorted information that can be of
+     <xref linkend="internals"> contains assorted information that may be of
      use to <productname>PostgreSQL</> developers.
     </para>
    </listitem>

doc/src/sgml/postgres.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/postgres.sgml,v 1.68 2004/12/03 05:50:18 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/postgres.sgml,v 1.69 2004/12/23 05:37:39 tgl Exp $
 -->
 
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [
@@ -67,7 +67,7 @@ $PostgreSQL: pgsql/doc/src/sgml/postgres.sgml,v 1.68 2004/12/03 05:50:18 momjian
     explain how to create the structures to hold data, how to populate
     the database, and how to query it.  The middle part lists the
     available data types and functions for use in
-    <acronym>SQL</acronym> data commands.  The rest treats several
+    <acronym>SQL</acronym> commands.  The rest treats several
     aspects that are important for tuning a database for optimal
     performance.
    </para>

doc/src/sgml/queries.sgml

@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/queries.sgml,v 1.31 2004/11/15 06:32:14 neilc Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/queries.sgml,v 1.32 2004/12/23 05:37:40 tgl Exp $ -->
 
 <chapter id="queries">
  <title>Queries</title>
@@ -477,7 +477,7 @@ FROM <replaceable>table_reference</replaceable> <optional>, <replaceable>table_r
     <para>
      A temporary name can be given to tables and complex table
      references to be used for references to the derived table in
-     further processing.  This is called a <firstterm>table
+     the rest of the query.  This is called a <firstterm>table
      alias</firstterm>.
     </para>
 
@@ -542,7 +542,8 @@ SELECT * FROM (my_table AS a CROSS JOIN my_table) AS b ...
     </para>
 
     <para>
-     Another form of table aliasing also gives temporary names to the columns of the table:
+     Another form of table aliasing gives temporary names to the columns of
+     the table, as well as the table itself:
 <synopsis>
 FROM <replaceable>table_reference</replaceable> <optional>AS</optional> <replaceable>alias</replaceable> ( <replaceable>column1</replaceable> <optional>, <replaceable>column2</replaceable> <optional>, ...</optional></optional> )
 </synopsis>
@@ -642,6 +643,7 @@ SELECT * FROM foo
                            where z.fooid = foo.fooid);
 
 CREATE VIEW vw_getfoo AS SELECT * FROM getfoo(1);
+
 SELECT * FROM vw_getfoo;
 </programlisting>
     </para>
@@ -679,12 +681,12 @@ SELECT *
 
    <para>
     The syntax of the <xref linkend="sql-where"
-    endterm="sql-where-title"> clause is
+    endterm="sql-where-title"> is
 <synopsis>
 WHERE <replaceable>search_condition</replaceable>
 </synopsis>
     where <replaceable>search_condition</replaceable> is any value
-    expression as defined in <xref linkend="sql-expressions"> that
+    expression (see <xref linkend="sql-expressions">) that
     returns a value of type <type>boolean</type>.
    </para>
 
@@ -694,17 +696,16 @@ WHERE <replaceable>search_condition</replaceable>
     condition.  If the result of the condition is true, the row is
     kept in the output table, otherwise (that is, if the result is
     false or null) it is discarded.  The search condition typically
-    references at least some column in the table generated in the
+    references at least some column of the table generated in the
     <literal>FROM</> clause; this is not required, but otherwise the
     <literal>WHERE</> clause will be fairly useless.
    </para>
 
    <note>
     <para>
-     Before the implementation of the <literal>JOIN</> syntax, it was
+     The join condition of an inner join can be written either in
-     necessary to put the join condition of an inner join in the
+     the <literal>WHERE</> clause or in the <literal>JOIN</> clause.
-     <literal>WHERE</> clause.  For example, these table expressions
+     For example, these table expressions are equivalent:
-     are equivalent:
 <programlisting>
 FROM a, b WHERE a.id = b.id AND b.val &gt; 5
 </programlisting>
@@ -788,7 +789,7 @@ SELECT <replaceable>select_list</replaceable>
     The <xref linkend="sql-groupby" endterm="sql-groupby-title"> 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
+    are listed does not matter.  The effect is to combine each set
     of rows sharing common values into one group row that is
     representative of all rows in the group.  This is done to
     eliminate redundancy in the output and/or compute aggregates that
@@ -818,7 +819,7 @@ SELECT <replaceable>select_list</replaceable>
     FROM test1 GROUP BY x</literal>, because there is no single value
     for the column <literal>y</> that could be associated with each
     group.  The grouped-by columns can be referenced in the select list since
-    they have a known constant value per group.
+    they have a single value in each group.
    </para>
 
    <para>
@@ -1055,14 +1056,14 @@ SELECT a AS value, b + c AS sum FROM ...
 
    <para>
     After the select list has been processed, the result table may
-    optionally be subject to the elimination of duplicates.  The
+    optionally be subject to the elimination of duplicate rows.  The
-    <literal>DISTINCT</literal> key word is written directly after the
+    <literal>DISTINCT</literal> key word is written directly after
-    <literal>SELECT</literal> to enable this:
+    <literal>SELECT</literal> to specify this:
 <synopsis>
 SELECT DISTINCT <replaceable>select_list</replaceable> ...
 </synopsis>
     (Instead of <literal>DISTINCT</> the key word <literal>ALL</literal>
-    can be used to select the default behavior of retaining all rows.)
+    can be used to specify the default behavior of retaining all rows.)
    </para>
 
    <para>
@@ -1153,8 +1154,8 @@ SELECT DISTINCT ON (<replaceable>expression</replaceable> <optional>, <replaceab
    <replaceable>query2</replaceable> to the result of
    <replaceable>query1</replaceable> (although there is no guarantee
    that this is the order in which the rows are actually returned).
-   Furthermore, it eliminates all duplicate rows, in the sense of
+   Furthermore, it eliminates duplicate rows from its result, in the same
-   <literal>DISTINCT</>, unless <literal>UNION ALL</> is used.
+   way as <literal>DISTINCT</>, unless <literal>UNION ALL</> is used.
   </para>
 
   <para>
@@ -1175,8 +1176,8 @@ SELECT DISTINCT ON (<replaceable>expression</replaceable> <optional>, <replaceab
   <para>
    In order to calculate the union, intersection, or difference of two
    queries, the two queries must be <quote>union compatible</quote>,
-   which means that they both return the same number of columns, and
+   which means that they return the same number of columns and
-   that the corresponding columns have compatible data types, as
+   the corresponding columns have compatible data types, as
    described in <xref linkend="typeconv-union-case">.
   </para>
  </sect1>
@@ -1196,7 +1197,7 @@ SELECT DISTINCT ON (<replaceable>expression</replaceable> <optional>, <replaceab
   <para>
    After a query has produced an output table (after the select list
    has been processed) it can optionally be sorted.  If sorting is not
-   chosen, the rows will be returned in random order.  The actual
+   chosen, the rows will be returned in an unspecified order.  The actual
    order in that case will depend on the scan and join plan types and
    the order on disk, but it must not be relied on.  A particular
    output ordering can only be guaranteed if the sort step is explicitly
@@ -1227,10 +1228,10 @@ SELECT a, sum(b) FROM table1 GROUP BY a ORDER BY 1;
 <programlisting>
 SELECT a, b FROM table1 ORDER BY a + b;
 </programlisting>
-   References to column names in the <literal>FROM</> clause that are
+   References to column names of the <literal>FROM</> clause that are
-   renamed in the select list are also allowed:
+   not present in the select list are also allowed:
 <programlisting>
-SELECT a AS b FROM table1 ORDER BY a;
+SELECT a FROM table1 ORDER BY b;
 </programlisting>
    But these extensions do not work in queries involving
    <literal>UNION</>, <literal>INTERSECT</>, or <literal>EXCEPT</>,
@@ -1325,6 +1326,12 @@ SELECT <replaceable>select_list</replaceable>
    deliver the results of a query in any particular order unless
    <literal>ORDER BY</> is used to constrain the order.
   </para>
+
+  <para>
+   The rows skipped by an <literal>OFFSET</> clause still have to be
+   computed inside the server; therefore a large <literal>OFFSET</>
+   can be inefficient.
+  </para>
  </sect1>
 
 </chapter>

doc/src/sgml/rowtypes.sgml

@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/rowtypes.sgml,v 2.3 2004/12/13 18:05:09 petere Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/rowtypes.sgml,v 2.4 2004/12/23 05:37:40 tgl Exp $ -->
 
 <sect1 id="rowtypes">
  <title>Composite Types</title>
@@ -308,6 +308,8 @@ INSERT ... VALUES ('("\\"\\\\")');
    with a data type whose input routine also treated backslashes specially,
    <type>bytea</> for example, we might need as many as eight backslashes
    in the command to get one backslash into the stored composite field.)
+   Dollar quoting (see <xref linkend="sql-syntax-dollar-quoting">) may be
+   used to avoid the need to double backslashes.
   </para>
  </note>
 

doc/src/sgml/syntax.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/syntax.sgml,v 1.98 2004/12/13 18:05:09 petere Exp $
+$PostgreSQL: pgsql/doc/src/sgml/syntax.sgml,v 1.99 2004/12/23 05:37:40 tgl Exp $
 -->
 
 <chapter id="sql-syntax">
@@ -599,7 +599,8 @@ CAST ( '<replaceable>string</replaceable>' AS <replaceable>type</replaceable> )
       A dollar sign (<literal>$</literal>) followed by digits is used
       to represent a positional parameter in the body of a function
       definition or a prepared statement.  In other contexts the
-      dollar sign may be part of an identifier.
+      dollar sign may be part of an identifier or a dollar-quoted string
+      constant.
      </para>
     </listitem>
 
@@ -646,8 +647,9 @@ CAST ( '<replaceable>string</replaceable>' AS <replaceable>type</replaceable> )
 
     <listitem>
      <para>
-      The asterisk (<literal>*</literal>) has a special meaning when
+      The asterisk (<literal>*</literal>) is used in some contexts to denote
-      used in the <command>SELECT</command> command or with the
+      all the fields of a table row or composite value.  It also
+      has a special meaning when used as the argument of the
       <function>COUNT</function> aggregate function.
      </para>
     </listitem>
@@ -823,7 +825,7 @@ SELECT (5 !) - 6;
       <row>
        <entry><token>BETWEEN</token></entry>
        <entry></entry>
-       <entry>containment</entry>
+       <entry>range containment</entry>
       </row>
 
       <row>
@@ -1552,7 +1554,9 @@ SELECT ROW(1,2.5,'this is a test');
     to avoid ambiguity.  For example:
 <programlisting>
 CREATE TABLE mytable(f1 int, f2 float, f3 text);
+
 CREATE FUNCTION getf1(mytable) RETURNS int AS 'SELECT $1.f1' LANGUAGE SQL;
+
 -- No cast needed since only one getf1() exists
 SELECT getf1(ROW(1,2.5,'this is a test'));
  getf1
@@ -1561,10 +1565,13 @@ SELECT getf1(ROW(1,2.5,'this is a test'));
 (1 row)
 
 CREATE TYPE myrowtype AS (f1 int, f2 text, f3 numeric);
+
 CREATE FUNCTION getf1(myrowtype) RETURNS int AS 'SELECT $1.f1' LANGUAGE SQL;
+
 -- Now we need a cast to indicate which function to call:
 SELECT getf1(ROW(1,2.5,'this is a test'));
 ERROR:  function getf1(record) is not unique
+
 SELECT getf1(ROW(1,2.5,'this is a test')::mytable);
  getf1
 -------
@@ -1587,6 +1594,7 @@ SELECT getf1(CAST(ROW(11,'this is a test',2.5) AS myrowtype));
    <literal>IS NULL</> or <literal>IS NOT NULL</>, for example
 <programlisting>
 SELECT ROW(1,2.5,'this is a test') = ROW(1, 3, 'not the same');
+
 SELECT ROW(a, b, c) IS NOT NULL FROM table;
 </programlisting>
    For more detail see <xref linkend="functions-comparisons">.