Doc: minor documentation improvements about extensions.

Document the formerly-undocumented behavior that schema and comment
control-file entries for an extension are honored only during initial
installation, whereas other properties are also honored during updates.

While at it, do some copy-editing on the recently-added docs for CREATE
EXTENSION ... CASCADE, use links for some formerly vague cross references,
and make a couple other minor improvements.

Back-patch to 9.6 where CASCADE was added.  The other parts of this
could go further back, but they're probably not important enough to
bother.

Author: tglsfdc

doc/src/sgml/extend.sgml

@@ -335,11 +335,13 @@
     by <application>pg_dump</>.  Such a change is usually only sensible if
     you concurrently make the same change in the extension's script file.
     (But there are special provisions for tables containing configuration
-    data; see below.)
+    data; see <xref linkend="extend-extensions-config-tables">.)
+    In production situations, it's generally better to create an extension
+    update script to perform changes to extension member objects.
    </para>
 
    <para>
-    The extension script may set privileges on objects which are part of the
+    The extension script may set privileges on objects that are part of the
     extension via <command>GRANT</command> and <command>REVOKE</command>
     statements.  The final set of privileges for each object (if any are set)
     will be stored in the
@@ -453,9 +455,11 @@
       <term><varname>comment</varname> (<type>string</type>)</term>
       <listitem>
        <para>
-        A comment (any string) about the extension.  Alternatively,
-        the comment can be set by means of the <xref linkend="sql-comment">
-        command in the script file.
+        A comment (any string) about the extension.  The comment is applied
+        when initially creating an extension, but not during extension updates
+        (since that might override user-added comments).  Alternatively,
+        the extension's comment can be set by writing
+        a <xref linkend="sql-comment"> command in the script file.
        </para>
       </listitem>
      </varlistentry>
@@ -518,7 +522,7 @@
         its contained objects into a different schema after initial creation
         of the extension.  The default is <literal>false</>, i.e. the
         extension is not relocatable.
-        See below for more information.
+        See <xref linkend="extend-extensions-relocation"> for more information.
        </para>
       </listitem>
      </varlistentry>
@@ -529,7 +533,10 @@
        <para>
         This parameter can only be set for non-relocatable extensions.
         It forces the extension to be loaded into exactly the named schema
-        and not any other.  See below for more information.
+        and not any other.
+        The <varname>schema</varname> parameter is consulted only when
+        initially creating an extension, not during extension updates.
+        See <xref linkend="extend-extensions-relocation"> for more information.
        </para>
       </listitem>
      </varlistentry>
@@ -562,7 +569,8 @@
      comments) by the extension mechanism.  This provision is commonly used
      to throw an error if the script file is fed to <application>psql</>
      rather than being loaded via <command>CREATE EXTENSION</> (see example
-     script below).  Without that, users might accidentally load the
+     script in <xref linkend="extend-extensions-example">).
+     Without that, users might accidentally load the
      extension's contents as <quote>loose</> objects rather than as an
      extension, a state of affairs that's a bit tedious to recover from.
     </para>
@@ -580,7 +588,7 @@
 
    </sect2>
 
-   <sect2>
+   <sect2 id="extend-extensions-relocation">
     <title>Extension Relocatability</title>
 
     <para>
@@ -678,7 +686,7 @@ SET LOCAL search_path TO @extschema@;
     </para>
    </sect2>
 
-   <sect2>
+   <sect2 id="extend-extensions-config-tables">
     <title>Extension Configuration Tables</title>
 
     <para>
@@ -762,7 +770,7 @@ SELECT pg_catalog.pg_extension_config_dump('my_config', 'WHERE NOT standard_entr
      out but the dump will not be able to be restored directly and user
      intervention will be required.
     </para>
-    
+
     <para>
      Sequences associated with <type>serial</> or <type>bigserial</> columns
      need to be directly marked to dump their state. Marking their parent
@@ -877,7 +885,7 @@ SELECT * FROM pg_extension_update_paths('<replaceable>extension_name</>');
     </para>
    </sect2>
 
-   <sect2>
+   <sect2 id="extend-extensions-example">
     <title>Extension Example</title>
 
     <para>

doc/src/sgml/ref/create_extension.sgml

@@ -95,35 +95,21 @@ CREATE EXTENSION [ IF NOT EXISTS ] <replaceable class="parameter">extension_name
         If not specified, and the extension's control file does not specify a
         schema either, the current default object creation schema is used.
        </para>
+
        <para>
-        If the extension specifies <literal>schema</> in its control file,
-        the schema cannot be overridden with <literal>SCHEMA</> clause.
-        The <literal>SCHEMA</> clause in this case works as follows:
-        <itemizedlist>
-         <listitem>
-          <para>
-           If <replaceable class="parameter">schema_name</replaceable> matches
-           the schema in control file, it will be used normally as there is no
-           conflict.
-          </para>
-         </listitem>
-         <listitem>
-          <para>
-           If the <literal>CASCADE</> clause is given, the
-           <replaceable class="parameter">schema_name</replaceable> will only
-           be used for the missing required extensions which do not specify
-           <literal>schema</> in their control files.
-          </para>
-         </listitem>
-         <listitem>
-          <para>
-           If <replaceable class="parameter">schema_name</replaceable> is not
-           the same as the one in extension's control file and the
-           <literal>CASCADE</> clause is not given, error will be thrown.
-          </para>
-         </listitem>
-        </itemizedlist>
+        If the extension specifies a <literal>schema</> parameter in its
+        control file, then that schema cannot be overridden with
+        a <literal>SCHEMA</> clause.  Normally, an error will be raised if
+        a <literal>SCHEMA</> clause is given and it conflicts with the
+        extension's <literal>schema</> parameter.  However, if
+        the <literal>CASCADE</> clause is also given,
+        then <replaceable class="parameter">schema_name</replaceable> is
+        ignored when it conflicts.  The
+        given <replaceable class="parameter">schema_name</replaceable> will be
+        used for installation of any needed extensions that do not
+        specify <literal>schema</> in their control files.
        </para>
+
        <para>
         Remember that the extension itself is not considered to be within any
         schema: extensions have unqualified names that must be unique
@@ -147,7 +133,8 @@ CREATE EXTENSION [ IF NOT EXISTS ] <replaceable class="parameter">extension_name
      <varlistentry>
       <term><replaceable class="parameter">old_version</replaceable></term>
       <listitem>
-       <para><literal>FROM</> <replaceable class="parameter">old_version</>
+       <para>
+        <literal>FROM</> <replaceable class="parameter">old_version</>
         must be specified when, and only when, you are attempting to install
         an extension that replaces an <quote>old style</> module that is just
         a collection of objects not packaged into an extension.  This option
@@ -174,10 +161,13 @@ CREATE EXTENSION [ IF NOT EXISTS ] <replaceable class="parameter">extension_name
       <term><literal>CASCADE</></term>
       <listitem>
        <para>
-        Try to install extension including the required dependencies
-        recursively. The <literal>SCHEMA</> option will be propagated
-        to the required extensions.  Other options are not recursively
-        applied when using this clause.
+        Automatically install any extensions that this extension depends on
+        that are not already installed.  Their dependencies are likewise
+        automatically installed, recursively.  The <literal>SCHEMA</> clause,
+        if given, applies to all extensions that get installed this way.
+        Other options of the statement are not applied to
+        automatically-installed extensions; in particular, their default
+        versions are always selected.
        </para>
       </listitem>
      </varlistentry>