Documentation fixes for FILLFACTOR patch. Minor other editorialization.

doc/src/sgml/ref/create_table_as.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/create_table_as.sgml,v 1.33 2006/07/02 02:23:18 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/create_table_as.sgml,v 1.34 2006/07/04 18:07:24 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -22,8 +22,7 @@ PostgreSQL documentation
 <synopsis>
 CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } ] TABLE <replaceable>table_name</replaceable>
     [ (<replaceable>column_name</replaceable> [, ...] ) ]
-    [ WITH OIDS | WITHOUT OIDS ]
-    [ WITH (FILLFACTOR = <replaceable>fillfactor</replaceable>) ]
+    [ WITH ( <replaceable class="PARAMETER">storage_parameter</replaceable> [= <replaceable class="PARAMETER">value</replaceable>] [, ... ] ) | WITH OIDS | WITHOUT OIDS ]
     [ ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP } ]
     [ TABLESPACE <replaceable class="PARAMETER">tablespace</replaceable> ]
     AS <replaceable>query</replaceable>
@@ -104,24 +103,32 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } ] TABLE <replaceable>table_name
    </varlistentry>
 
    <varlistentry>
-    <term><literal>WITH OIDS</literal></term>
-    <term><literal>WITHOUT OIDS</literal></term>
-     <listitem>
-      <para>
-       This optional clause specifies whether the table created by
-       <command>CREATE TABLE AS</command> should include OIDs. If
-       neither form of this clause is specified, the value of the
-       <xref linkend="guc-default-with-oids"> configuration parameter is
-       used.
-      </para>
-     </listitem>
+    <term><literal>WITH ( <replaceable class="PARAMETER">storage_parameter</replaceable> [= <replaceable class="PARAMETER">value</replaceable>] [, ... ] )</literal></term>
+    <listitem>
+     <para>
+      This clause specifies optional storage parameters for the new table;
+      see <xref linkend="sql-createtable-storage-parameters"
+      endterm="sql-createtable-storage-parameters-title"> for more
+      information.  The <literal>WITH</> clause
+      can also include <literal>OIDS=TRUE</> (or just <literal>OIDS</>)
+      to specify that rows of the new table
+      should have OIDs (object identifiers) assigned to them, or
+      <literal>OIDS=FALSE</> to specify that the rows should not have OIDs.
+      See <xref linkend="sql-createtable"
+      endterm="sql-createtable-title"> for more information.
+     </para>
+    </listitem>
    </varlistentry>
 
    <varlistentry>
-    <term><literal>WITH (FILLFACTOR = <replaceable>fillfactor</replaceable>)</literal></term>
+    <term><literal>WITH OIDS</></term>
+    <term><literal>WITHOUT OIDS</></term>
     <listitem>
      <para>
-      This optional clause specifies the table's fillfactor in percentage.
+      These are obsolescent syntaxes equivalent to <literal>WITH (OIDS)</>
+      and <literal>WITH (OIDS=FALSE)</>, respectively.  If you wish to give
+      both an <literal>OIDS</> setting and storage parameters, you must use
+      the <literal>WITH ( ... )</> syntax; see above.
      </para>
     </listitem>
    </varlistentry>
@@ -225,7 +232,7 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } ] TABLE <replaceable>table_name
    this variable is false by default, so the default behavior is not
    identical to pre-8.0 releases.  Applications that
    require OIDs in the table created by <command>CREATE TABLE
-   AS</command> should explicitly specify <literal>WITH OIDS</literal>
+   AS</command> should explicitly specify <literal>WITH (OIDS)</literal>
    to ensure proper behavior.
   </para>
  </refsect1>
@@ -244,15 +251,14 @@ CREATE TABLE films_recent AS
   </para>
 
   <para>
-   Create a new temporary table that will be dropped at commit
-   <literal>films_recent</literal> with oids consisting of only
-   recent entries from the table <literal>films</literal> using a
-   prepared statement:
+   Create a new temporary table <literal>films_recent</literal>, consisting of
+   only recent entries from the table <literal>films</literal>, using a
+   prepared statement.  The new table has OIDs and will be dropped at commit:
 
 <programlisting>
 PREPARE recentfilms(date) AS
   SELECT * FROM films WHERE date_prod &gt; $1;
-CREATE TEMP TABLE films_recent WITH OIDS ON COMMIT DROP AS
+CREATE TEMP TABLE films_recent WITH (OIDS) ON COMMIT DROP AS
   EXECUTE recentfilms('2002-01-01');
 </programlisting>
   </para>
@@ -280,13 +286,8 @@ CREATE TEMP TABLE films_recent WITH OIDS ON COMMIT DROP AS
       this is not currently implemented by <productname>PostgreSQL</>.
       The behavior provided by <productname>PostgreSQL</> is equivalent
       to the standard's <literal>WITH DATA</literal> case.
-     </para>
-    </listitem>
-
-    <listitem>
-     <para>
-      <literal>WITH/WITHOUT OIDS</> is a <productname>PostgreSQL</>
-      extension.
+      <literal>WITH NO DATA</literal> can be simulated by appending
+      <literal>LIMIT 0</> to the query.
      </para>
     </listitem>
 
@@ -299,6 +300,13 @@ CREATE TEMP TABLE films_recent WITH OIDS ON COMMIT DROP AS
      </para>
     </listitem>
 
+    <listitem>
+     <para>
+      The <literal>WITH</> clause is a <productname>PostgreSQL</productname>
+      extension; neither storage parameters nor OIDs are in the standard.
+     </para>
+    </listitem>
+
     <listitem>
      <para>
       The <productname>PostgreSQL</productname> concept of tablespaces is not