Make the CREATE TABLE ref page more readable and update some information.

doc/src/sgml/ref/alter_table.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/alter_table.sgml,v 1.29 2001/10/12 00:07:14 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/alter_table.sgml,v 1.30 2001/10/22 18:14:47 petere Exp $
 Postgres documentation
 -->
 
@@ -161,15 +161,14 @@ ALTER TABLE <replaceable class="PARAMETER">table</replaceable>
   <para>
    <command>ALTER TABLE</command> changes the definition of an existing table.
    The <literal>ADD COLUMN</literal> form adds a new column to the table
-   using the same syntax as <xref linkend="SQL-CREATETABLE"
-   endterm="SQL-CREATETABLE-title">.
+   using the same syntax as <xref linkend="SQL-CREATETABLE">.
    The <literal>ALTER COLUMN SET/DROP DEFAULT</literal> forms
    allow you to set or remove the default for the column. Note that defaults
    only apply to subsequent <command>INSERT</command> commands; they do not
    cause rows already in the table to change.
    The <literal>ALTER COLUMN SET STATISTICS</literal> form allows you to
    set the statistics-gathering target for subsequent
-   <xref linkend="sql-analyze" endterm="sql-analyze-title"> operations.
+   <xref linkend="sql-analyze"> operations.
    The <literal>RENAME</literal> clause causes the name of a table or column
    to change without changing any of the data contained in
    the affected table. Thus, the table or column will
@@ -177,7 +176,7 @@ ALTER TABLE <replaceable class="PARAMETER">table</replaceable>
    executed.
    The ADD <replaceable class="PARAMETER">table constraint definition</replaceable> clause 
    adds a new constraint to the table using the same syntax as <xref
-   linkend="SQL-CREATETABLE" endterm="SQL-CREATETABLE-title">. 
+   linkend="SQL-CREATETABLE">. 
    The DROP CONSTRAINT <replaceable class="PARAMETER">constraint</replaceable> clause 
    drops all CHECK constraints on the table (and its children) that match <replaceable class="PARAMETER">constraint</replaceable>.
    The OWNER clause changes the owner of the table to the user <replaceable class="PARAMETER">
@@ -205,18 +204,17 @@ ALTER TABLE <replaceable class="PARAMETER">table</replaceable>
     You can use the <literal>SET DEFAULT</literal> form
     of <command>ALTER TABLE</command> to set the default later.
     (You may also want to update the already existing rows to the
-    new default value, using <xref linkend="sql-update"
-    endterm="sql-update-title">.)
+    new default value, using <xref linkend="sql-update">.)
    </para>
 
 	<para>
     Currently only CHECK constraints can be dropped from a table.  The RESTRICT
 	 keyword is required, although dependencies are not checked.  The CASCADE
 	 option is unsupported.  To remove a PRIMARY or UNIQUE constraint, drop the 
-	 relevant index using the <xref linkend="SQL-DROPINDEX" endterm="SQL-DROPINDEX-TITLE"> command.
+	 relevant index using the <xref linkend="SQL-DROPINDEX"> command.
     To remove FOREIGN KEY constraints you need to recreate
     and reload the table, using other parameters to the
-    <xref linkend="SQL-CREATETABLE" endterm="SQL-CREATETABLE-title">
+    <xref linkend="SQL-CREATETABLE">
     command.
    </para>
    <para>

doc/src/sgml/ref/create_table_as.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_table_as.sgml,v 1.7 2001/09/03 12:57:49 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_table_as.sgml,v 1.8 2001/10/22 18:14:47 petere Exp $
 Postgres documentation
 -->
 
 <refentry id="SQL-CREATETABLEAS">
  <refmeta>
-  <refentrytitle id="SQL-CREATETABLEAS-TITLE">
-   CREATE TABLE AS
-  </refentrytitle>
+  <refentrytitle>CREATE TABLE AS</refentrytitle>
   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  </refmeta>
+
  <refnamediv>
-  <refname>
-   CREATE TABLE AS
-  </refname>
-  <refpurpose>
-   create a new table from the results of a query
-  </refpurpose>
+  <refname>CREATE TABLE AS</refname>
+  <refpurpose>create a new table from the results of a query</refpurpose>
  </refnamediv>
+
  <refsynopsisdiv>
-  <refsynopsisdivinfo>
-   <date>2001-03-03</date>
-  </refsynopsisdivinfo>
-  <synopsis>
-CREATE [ TEMPORARY | TEMP ] TABLE <replaceable>table</replaceable> [ (<replaceable>column</replaceable> [, ...] ) ]
-     AS <replaceable>select_clause</replaceable>
+<synopsis>
+CREATE [ [ LOCAL ] { TEMPORARY | TEMP } ] TABLE <replaceable>table_name</replaceable> [ (<replaceable>column_name</replaceable> [, ...] ) ]
+    AS <replaceable>query</replaceable>
   </synopsis>
+ </refsynopsisdiv>
   
-  <refsect2>
-   <refsect2info>
-    <date>1998-09-22</date>
-   </refsect2info>
+ <refsect1>
+  <refsect1info>
+   <date>2001-03-20</date>
+  </refsect1info>
   <title>
-    Inputs
+   Description
   </title>
   <para>
+   <command>CREATE TABLE AS</command> creates a table and fills it
+   with data computed by a <command>SELECT</command> command.  The
+   table columns have the names and data types associated with the
+   output columns of the <command>SELECT</command> (except that you
+   can override the column names by giving an explicit list of new
+   column names).
+  </para>
+
+  <para>
+   <command>CREATE TABLE AS</command> bears some resemblance to
+   creating a view, but it is really quite different: it creates a new
+   table and evaluates the query just once to fill the new table
+   initially.  The new table will not track subsequent changes to the
+   source tables of the query.  In contrast, a view re-evaluates the
+   underlying <command>SELECT</command> statements whenever it is
+   queried.
+  </para>
+ </refsect1>
+
+ <refsect1>
+  <title>Parameters</title>
    
   <variablelist>
    <varlistentry>
-      <term>TEMPORARY or TEMP</term>
+    <term><literal>[LOCAL] TEMPORARY</> or <literal>[LOCAL] TEMP</></term>
     <listitem>
      <para>
-	If specified, the table is created only within this session, and is
-	automatically dropped on session exit.
-	Existing permanent tables with the same name are not visible
-	(in this session) while the temporary table exists.
+      If specified, the table is created as a temporary table.
+      Temporary tables are automatically dropped at the end of a
+      session.  Existing persistent tables with the same name are not
+      visible to the current session while the temporary table exists.
       Any indexes created on a temporary table are automatically
       temporary as well.
      </para>
+
+     <para>
+      The <literal>LOCAL</literal> word is optional.
+     </para>
     </listitem>
    </varlistentry>
 
    <varlistentry>
-     <term><replaceable>table</replaceable></term>
+    <term><replaceable>table_name</replaceable></term>
     <listitem>
      <para>
-        The name of the new table to be created.
-	This table must not already exist.  However, a temporary table
-	can be created that has the same name as an existing permanent
-	table.
+      The name of the new table to be created.  This table must not
+      already exist.  However, a temporary table can be created that
+      has the same name as an existing permanent table.
      </para>
     </listitem>
    </varlistentry>
 
    <varlistentry>
-      <term><replaceable>column</replaceable></term>
+    <term><replaceable>column_name</replaceable></term>
     <listitem>
      <para>
-	The name of a column. Multiple column names can be specified using
-	a comma-delimited list of column names.  If column names are not
-	provided, they are taken from the output column names of the
-	SELECT query.
+      The name of a column in the new table. Multiple column names can
+      be specified using a comma-delimited list of column names.  If
+      column names are not provided, they are taken from the output
+      column names of the query.
      </para>
     </listitem>
    </varlistentry>
 
    <varlistentry>
-      <term><replaceable>select_clause</replaceable></term>
+    <term><replaceable>query</replaceable></term>
     <listitem>
      <para>
-	A valid query statement. Refer to
-	<xref linkend="sql-select" endterm="sql-select-title">
+      A query statement (that is, a <command>SELECT</command>
+      command).  Refer to
+      <xref linkend="sql-select">
       for a description of the allowed syntax.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
-   </para>
-  </refsect2>
+ </refsect1>
 
-  <refsect2>
-   <refsect2info>
-    <date>1998-09-22</date>
-   </refsect2info>
-   <title>
-    Outputs
-   </title>
+ <refsect1>
+  <title>Diagnostics</title>
 
   <para>
-    Refer to
-    <xref linkend="sql-createtable" endterm="sql-createtable-title">
-    and
-    <xref linkend="sql-select" endterm="sql-select-title">
+   Refer to <xref linkend="sql-createtable"> and
+   <xref linkend="sql-select">
    for a summary of possible output messages.
   </para>
-  </refsect2>
- </refsynopsisdiv>
+ </refsect1>
 
  <refsect1>
-  <refsect1info>
-   <date>2001-03-20</date>
-  </refsect1info>
-  <title>
-   Description
-  </title>
+  <title>Notes</title>
+
   <para>
-   <command>CREATE TABLE AS</command> creates a table and fills it
-   with data computed by a <command>SELECT</command> command.  The
-   table columns have the names and datatypes associated with the
-   output columns of the <command>SELECT</command> (except that you
-   can override the <command>SELECT</command> column names by giving
-   an explicit list of column names).
+   This command is functionally equivalent to <xref
+   linkend="sql-selectinto">, but it is preferred since it is less
+   likely to be confused with other uses of the <command>SELECT
+   ... INTO</command> syntax.
   </para>
+ </refsect1>
+
+ <refsect1>
+  <title>Compatibility</title>
 
   <para>
-   <command>CREATE TABLE AS</command> bears some resemblance to creating
-   a view, but it is really quite different: it creates a new table and
-   evaluates the <command>SELECT</command> just once to fill the new table
-   initially.  The new table will not track subsequent changes to
-   the source tables of the <command>SELECT</command>.  In contrast,
-   a view re-evaluates the given <command>SELECT</command> whenever queried.
+   This command is modeled after an <productname>Oracle</productname>
+   feature.  There is no command with equivalent functionality in
+   SQL92 or SQL99.  However, a combination of <literal>CREATE
+   TABLE</literal> and <literal>INSERT ... SELECT</literal> can
+   accomplish the same thing with little more effort.
   </para>
+ </refsect1>
+
+ <refsect1>
+  <title>History</title>
 
   <para>
-   This command is functionally equivalent to
-   <xref linkend="sql-selectinto" endterm="sql-selectinto-title">,
-   but it is preferred since it is less likely to be confused with
-   other uses of the <command>SELECT ... INTO</command> syntax.
+   The <command>CREATE TABLE AS</command> command has been available
+   since <productname>PostgreSQL</productname> 6.3.
   </para>
  </refsect1>
+
+ <refsect1>
+  <title>See Also</title>
+
+  <simplelist type="inline">
+   <member><xref linkend="sql-createtable"></member>
+   <member><xref linkend="sql-createview"></member>
+   <member><xref linkend="sql-select"></member>
+   <member><xref linkend="sql-selectinto"></member>
+  </simplelist>
+ </refsect1>
+ 
 </refentry>
 
 <!-- Keep this comment at the end of the file

doc/src/sgml/ref/select_into.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/select_into.sgml,v 1.12 2001/09/23 13:34:44 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/select_into.sgml,v 1.13 2001/10/22 18:14:47 petere Exp $
 Postgres documentation
 -->
 
@@ -89,7 +89,7 @@ where <replaceable class="PARAMETER">from_item</replaceable> can be:
 
    <para>
     All other inputs are described in detail for
-    <xref linkend="sql-select" endterm="sql-select-title">.
+    <xref linkend="sql-select">.
    </para>
   </refsect2>
 
@@ -103,9 +103,9 @@ where <replaceable class="PARAMETER">from_item</replaceable> can be:
 
    <para>
     Refer to
-    <xref linkend="sql-createtable" endterm="sql-createtable-title">
+    <xref linkend="sql-createtable">
     and
-    <xref linkend="sql-select" endterm="sql-select-title">
+    <xref linkend="sql-select">
     for a summary of possible output messages.
    </para>
   </refsect2>
@@ -128,7 +128,7 @@ where <replaceable class="PARAMETER">from_item</replaceable> can be:
 
    <note>
     <para>
-     <xref linkend="sql-createtableas" endterm="sql-createtableas-title">
+     <xref linkend="sql-createtableas">
      is functionally equivalent to <command>SELECT INTO</command>.
      <command>CREATE TABLE AS</command> is the recommended syntax, since
      <command>SELECT INTO</command> is not standard.  In fact, this form of

doc/src/sgml/stylesheet.dsl

-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/stylesheet.dsl,v 1.14 2001/10/09 18:46:00 petere Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/stylesheet.dsl,v 1.15 2001/10/22 18:14:47 petere Exp $ -->
 <!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
 
 <!-- must turn on one of these with -i on the jade command line -->
@@ -123,6 +123,16 @@
 ;;; XXX The above is very ugly.  It might be better to run 'tidy' on
 ;;; the resulting *.html files.
 
+
+;; Format multiple terms in varlistentry vertically, instead
+;; of comma-separated.
+(element (varlistentry term)
+  (make sequence
+    (process-children-trim)
+    (if (not (last-sibling?))
+        (make empty-element gi: "BR")
+        (empty-sosofo))))
+
 ]]> <!-- %output-html -->
 
 <![ %output-print; [