doc: Reorganize CREATE TABLE / LIKE option documentation

This section once started out small but has now grown quite a bit and
needs a bit of structure.

Rewrite as list, add documentation of EXCLUDING, and improve the
documentation of INCLUDING ALL instead of just listing all the options
again.

per report from Yugo Nagata that EXCLUDING was not documented, that part
reviewed by Daniel Gustafsson, most of the rewrite was by me

diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml
index 2a1eac9592b19e40eaefc2125896d73e391daaee..b449520940929d8be6c695141d5bd8cfeae8f929 100644 (file)
--- a/doc/src/sgml/ref/create_table.sgml
+++ b/doc/src/sgml/ref/create_table.sgml
@@ -570,66 +570,124 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       possible to include data of the new table in scans of the original
       table.
      </para>
-     <para>
-      Default expressions for the copied column definitions will be copied
-      only if <literal>INCLUDING DEFAULTS</literal> is specified.  The
-      default behavior is to exclude default expressions, resulting in the
-      copied columns in the new table having null defaults.
-      Note that copying defaults that call database-modification functions,
-      such as <function>nextval</function>, may create a functional linkage between
-      the original and new tables.
-     </para>
-     <para>
-      Any identity specifications of copied column definitions will only be
-      copied if <literal>INCLUDING IDENTITY</literal> is specified.  A new
-      sequence is created for each identity column of the new table, separate
-      from the sequences associated with the old table.
-     </para>
-     <para>
-      Not-null constraints are always copied to the new table.
-      <literal>CHECK</literal> constraints will be copied only if
-      <literal>INCLUDING CONSTRAINTS</literal> is specified.
-      No distinction is made between column constraints and table
-      constraints.
-     </para>
-     <para>
-      Extended statistics are copied to the new table if
-      <literal>INCLUDING STATISTICS</literal> is specified.
-     </para>
-     <para>
-      Indexes, <literal>PRIMARY KEY</literal>, <literal>UNIQUE</literal>,
-      and <literal>EXCLUDE</literal> constraints on the original table will be
-      created on the new table only if <literal>INCLUDING INDEXES</literal>
-      is specified.  Names for the new indexes and constraints are
-      chosen according to the default rules, regardless of how the originals
-      were named.  (This behavior avoids possible duplicate-name failures for
-      the new indexes.)
-     </para>
-     <para>
-      <literal>STORAGE</literal> settings for the copied column definitions will be
-      copied only if <literal>INCLUDING STORAGE</literal> is specified.  The
-      default behavior is to exclude <literal>STORAGE</literal> settings, resulting
-      in the copied columns in the new table having type-specific default
-      settings.  For more on <literal>STORAGE</literal> settings, see
-      <xref linkend="storage-toast"/>.
-     </para>
-     <para>
-      Comments for the copied columns, constraints, and indexes
-      will be copied only if <literal>INCLUDING COMMENTS</literal>
-      is specified. The default behavior is to exclude comments, resulting in
-      the copied columns and constraints in the new table having no comments.
-     </para>
-     <para>
-      <literal>INCLUDING ALL</literal> is an abbreviated form of
-      <literal>INCLUDING COMMENTS INCLUDING CONSTRAINTS INCLUDING DEFAULTS INCLUDING IDENTITY INCLUDING INDEXES INCLUDING STATISTICS INCLUDING STORAGE</literal>.
-     </para>
-     <para>
-      Note that unlike <literal>INHERITS</literal>, columns and
+      <para>
+      Also unlike <literal>INHERITS</literal>, columns and
       constraints copied by <literal>LIKE</literal> are not merged with similarly
       named columns and constraints.
       If the same name is specified explicitly or in another
       <literal>LIKE</literal> clause, an error is signaled.
      </para>
+     <para>
+      The optional <replaceable>like_option</replaceable> clauses specify
+      which additional properties of the original table to copy.  Specifying
+      <literal>INCLUDING</literal> copies the property, specifying
+      <literal>EXCLUDING</literal> omits the property.
+      <literal>EXCLUDING</literal> is the default.  If multiple specifications
+      are made for the same kind of object, the last one is used.  The
+      available options are:
+
+      <variablelist>
+       <varlistentry>
+        <term><literal>INCLUDING COMMENTS</literal></term>
+        <listitem>
+         <para>
+          Comments for the copied columns, constraints, and indexes will be
+          copied.  The default behavior is to exclude comments, resulting in
+          the copied columns and constraints in the new table having no
+          comments.
+         </para>
+        </listitem>
+       </varlistentry>
+
+       <varlistentry>
+        <term><literal>INCLUDING CONSTRAINTS</literal></term>
+        <listitem>
+         <para>
+          <literal>CHECK</literal> constraints will be copied.  No distinction
+          is made between column constraints and table constraints.  Not-null
+          constraints are always copied to the new table.
+         </para>
+        </listitem>
+       </varlistentry>
+
+       <varlistentry>
+        <term><literal>INCLUDING DEFAULTS</literal></term>
+        <listitem>
+         <para>
+          Default expressions for the copied column definitions will be
+          copied.  Otherwise, default expressions are not copied, resulting in
+          the copied columns in the new table having null defaults.  Note that
+          copying defaults that call database-modification functions, such as
+          <function>nextval</function>, may create a functional linkage
+          between the original and new tables.
+         </para>
+        </listitem>
+       </varlistentry>
+
+       <varlistentry>
+        <term><literal>INCLUDING IDENTITY</literal></term>
+        <listitem>
+         <para>
+          Any identity specifications of copied column definitions will be
+          copied.  A new sequence is created for each identity column of the
+          new table, separate from the sequences associated with the old
+          table.
+         </para>
+        </listitem>
+       </varlistentry>
+
+       <varlistentry>
+        <term><literal>INCLUDING INDEXES</literal></term>
+        <listitem>
+         <para>
+          Indexes, <literal>PRIMARY KEY</literal>, <literal>UNIQUE</literal>,
+          and <literal>EXCLUDE</literal> constraints on the original table
+          will be created on the new table.  Names for the new indexes and
+          constraints are chosen according to the default rules, regardless of
+          how the originals were named.  (This behavior avoids possible
+          duplicate-name failures for the new indexes.)
+         </para>
+        </listitem>
+       </varlistentry>
+
+       <varlistentry>
+        <term><literal>INCLUDING STATISTICS</literal></term>
+        <listitem>
+         <para>
+          Extended statistics are copied to the new table.
+         </para>
+        </listitem>
+       </varlistentry>
+
+       <varlistentry>
+        <term><literal>INCLUDING STORAGE</literal></term>
+        <listitem>
+         <para>
+          <literal>STORAGE</literal> settings for the copied column
+          definitions will be copied.  The default behavior is to exclude
+          <literal>STORAGE</literal> settings, resulting in the copied columns
+          in the new table having type-specific default settings.  For more on
+          <literal>STORAGE</literal> settings, see <xref
+          linkend="storage-toast"/>.
+         </para>
+        </listitem>
+       </varlistentry>
+
+       <varlistentry>
+        <term><literal>INCLUDING ALL</literal></term>
+        <listitem>
+         <para>
+          <literal>INCLUDING ALL</literal> is an abbreviated form selecting
+          all the available individual options.  (It could be useful to write
+          individual <literal>EXCLUDING</literal> clauses after
+          <literal>INCLUDING ALL</literal> to select all but some specific
+          options.)
+         </para>
+        </listitem>
+       </varlistentry>
+      </variablelist>
+     </para>
+
      <para>
       The <literal>LIKE</literal> clause can also be used to copy column
       definitions from views, foreign tables, or composite types.