Assorted small doc patches

commit 73fa486a855d75d74a1a695bb350bfbfe27c7751
Author: David G. Johnston <david.g.johnston@gmail.com>
Date:   Tue Apr 12 21:23:53 2022 +0000

    doc: make unique non-null join selectivity example match the prose
    
    The description of the computation for the unique, non-null,
    join selectivity describes a division by the maximum of two values,
    while the example shows a multiplication by their reciprocal.  While
    equivalent the max phrasing is easier to understand; which seems
    more important here than precisely adhering to the formula use
    in the code (for which either variant is still an approximation).
    
    While both num_distinct and num_rows are equal for a unique column
    both the concept and formula use row count (10,000) and the
    field num_distinct has already been set to mean the specific value
    present in the pg_stats table (i.e, -1), so use num_rows here.

diff --git a/doc/src/sgml/planstats.sgml b/doc/src/sgml/planstats.sgml
index 78053d7c49..f72bc4b274 100644
--- a/doc/src/sgml/planstats.sgml
+++ b/doc/src/sgml/planstats.sgml
@@ -391,18 +391,20 @@ tablename  | null_frac | n_distinct | most_common_vals
 </programlisting>
 
    In this case there is no <acronym>MCV</acronym> information for
-   <structfield>unique2</structfield> because all the values appear to be
-   unique, so we use an algorithm that relies only on the number of
-   distinct values for both relations together with their null fractions:
+   <structname>unique2</structname> and all the values appear to be
+   unique (n_distinct = -1), so we use an algorithm that relies on the row
+   count estimates for both relations (num_rows, not shown, but "tenk")
+   together with the column null fractions (zero for both):
 
 <programlisting>
-selectivity = (1 - null_frac1) * (1 - null_frac2) * min(1/num_distinct1, 1/num_distinct2)
+selectivity = (1 - null_frac1) * (1 - null_frac2) / max(num_rows1, num_rows2)
             = (1 - 0) * (1 - 0) / max(10000, 10000)
             = 0.0001
 </programlisting>
 
    This is, subtract the null fraction from one for each of the relations,
-   and divide by the maximum of the numbers of distinct values.
+   and divide by the row count of the larger relation (this value does get
+   scaled in the non-unique case).
    The number of rows
    that the join is likely to emit is calculated as the cardinality of the
    Cartesian product of the two inputs, multiplied by the

commit 60491d8e4a8ca557cfdb07029c5ebbde341c2c1d
Author: David G. Johnston <david.g.johnston@gmail.com>
Date:   Tue Apr 12 02:25:01 2022 +0000

    Fix a few instances of default database name descriptions.
    
    The default database name is just the user name, not the
    operating-system user name.
    
    In passing, the authentication error examples use the phrase
    "database user name" in a couple of locations.  The word
    database in both cases is both unusual and unnecesssary for
    understanding.
    
    Furthermore, it seems better to tell the reader the likely
    reason why the displayed database name happens to be a user name.

diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml
index 142b0affcb..9b2323cde7 100644
--- a/doc/src/sgml/client-auth.sgml
+++ b/doc/src/sgml/client-auth.sgml
@@ -2218,7 +2218,7 @@ FATAL:  password authentication failed for user "andym"
 <programlisting>
 FATAL:  user "andym" does not exist
 </programlisting>
-    The indicated database user name was not found.
+    The indicated user name was not found.
    </para>
 
    <para>
@@ -2226,8 +2226,9 @@ FATAL:  user "andym" does not exist
 FATAL:  database "testdb" does not exist
 </programlisting>
     The database you are trying to connect to does not exist. Note that
-    if you do not specify a database name, it defaults to the database
-    user name, which might or might not be the right thing.
+    if the database name shown matches the user name you are connecting
+    as it is not by accident: the default database name is the
+    user name.
    </para>
 
    <tip>
diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index 592356019b..c17fe7a9e5 100644
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -657,7 +657,7 @@ EOF
     determined at compile time.
     Since the database server uses the same default, you will not have
     to specify the port in most cases. The default user name is your
-    operating-system user name, as is the default database name.
+    operating-system user name. The default database name is the resolved user name.
     Note that you cannot
     just connect to any database under any user name. Your database
     administrator should have informed you about your access rights.

commit e921441f22bad972393144628c7ee48845d5384c
Author: David G. Johnston <david.g.johnston@gmail.com>
Date:   Tue Apr 12 14:30:11 2022 +0000

    doc: Improve docs regarding savepoint name reuse
    
    Per documentation comment the savepoint command lacks an example
    where the savepoint name is reused.  The suggested example didn't
    conform to the others on the page, nor did the suggested location
    in compatibility seem desirable, but the omission rang true. Add
    another example to the examples section demonstrating this case.
    Additionally, document under the description for savepoint_name
    that we allow for the name to be repeated - and note what that
    means in terms of release and rollback. It seems desirable to
    place this comment in description rather than notes for savepoint.
    For the other two commands the behavior in the presence of
    duplicate savepoint names best fits as notes.  In fact release
    already had one.  This commit copies the same verbiage over to
    rollback.

diff --git a/doc/src/sgml/ref/rollback_to.sgml b/doc/src/sgml/ref/rollback_to.sgml
index 3d5a241e1a..7bd1b41feb 100644
--- a/doc/src/sgml/ref/rollback_to.sgml
+++ b/doc/src/sgml/ref/rollback_to.sgml
@@ -89,6 +89,12 @@ ROLLBACK [ WORK | TRANSACTION ] TO [ SAVEPOINT ] <replaceable>savepoint_name</re
    cannot-execute state, so while the transaction can be restored using
    <command>ROLLBACK TO SAVEPOINT</command>, the cursor can no longer be used.
   </para>
+
+  <para>
+   If multiple savepoints have the same name, only the one that was most
+   recently defined is released.
+  </para>
+
  </refsect1>
 
  <refsect1>
diff --git a/doc/src/sgml/ref/savepoint.sgml b/doc/src/sgml/ref/savepoint.sgml
index b17342a1ee..fd017935ea 100644
--- a/doc/src/sgml/ref/savepoint.sgml
+++ b/doc/src/sgml/ref/savepoint.sgml
@@ -53,7 +53,9 @@ SAVEPOINT <replaceable>savepoint_name</replaceable>
     <term><replaceable>savepoint_name</replaceable></term>
     <listitem>
      <para>
-      The name to give to the new savepoint.
+      The name to give to the new savepoint.  The name may already exist,
+      in which case a rollback or release to the same name will use the
+      one that was most recently defined.
      </para>
     </listitem>
    </varlistentry>
@@ -106,6 +108,25 @@ COMMIT;
 </programlisting>
    The above transaction will insert both 3 and 4.
   </para>
+
+  <para>
+  To use a single savepoint name:
+<programlisting>
+BEGIN;
+    INSERT INTO table1 VALUES (1);
+    SAVEPOINT my_savepoint;
+    INSERT INTO table1 VALUES (2);
+    SAVEPOINT my_savepoint;
+    INSERT INTO table1 VALUES (3);
+    ROLLBACK TO SAVEPOINT my_savepoint;
+    SELECT * FROM table1; // 1, 2
+    ROLLBACK TO SAVEPOINT my_savepoint;
+    SELECT * FROM table1; // just 1
+COMMIT;
+</programlisting>
+  The above transaction shows row 3 being rolled back first then row 2.
+  </para>
+
  </refsect1>
 
  <refsect1>

commit 3ae125aafb5bad062952be1e9f97cb2288350f5b
Author: David G. Johnston <david.g.johnston@gmail.com>
Date:   Tue Apr 12 02:51:18 2022 +0000

    doc: For INSERT ON CONFLICT excluded is a only a name, not a table.
    
    As one cannot place excluded in a FROM clause (subquery) in the
    ON CONFLICT clause referring to it as a table, with plural rows
    nonetheless, leads the reader to infer more about what the
    behavior here is than is correct. We already just say use the
    table's name for the existing row so just match that pattern
    of using the name excluded for the proposed row.
    
    The alias description doesn't have the same issue regarding the
    use of the word table and rows, as the use there is more conceptual,
    but the wording about "otherwise taken as" is wrong: rather two
    labels of excluded end up in scope and you get an ambigious name error.
    
    The error messages still consider excluded to be a table reference
    and this patch does not try to change that.  That implementation
    detail need not force the user-facing documentation for the feature
    to use the term table when it doesn't really apply.

diff --git a/doc/src/sgml/ref/insert.sgml b/doc/src/sgml/ref/insert.sgml
index a9af9959c0..0fad1d3640 100644
--- a/doc/src/sgml/ref/insert.sgml
+++ b/doc/src/sgml/ref/insert.sgml
@@ -175,9 +175,8 @@ INSERT INTO <replaceable class="parameter">table_name</replaceable> [ AS <replac
         class="parameter">table_name</replaceable>.  When an alias is
         provided, it completely hides the actual name of the table.
         This is particularly useful when <literal>ON CONFLICT DO UPDATE</literal>
-        targets a table named <varname>excluded</varname>, since that will otherwise
-        be taken as the name of the special table representing rows proposed
-        for insertion.
+        targets a table named <varname>excluded</varname>, since that will
+        conflict with the special name representing the row proposed for insertion.
        </para>
       </listitem>
      </varlistentry>
@@ -396,8 +395,8 @@ INSERT INTO <replaceable class="parameter">table_name</replaceable> [ AS <replac
         conflict.  The <literal>SET</literal> and
         <literal>WHERE</literal> clauses in <literal>ON CONFLICT DO
         UPDATE</literal> have access to the existing row using the
-        table's name (or an alias), and to rows proposed for insertion
-        using the special <varname>excluded</varname> table.
+        table's name (or an alias), and to the proposed row
+        using the name <varname>excluded</varname>.
         <literal>SELECT</literal> privilege is required on any column in the
         target table where corresponding <varname>excluded</varname>
         columns are read.
@@ -699,8 +698,8 @@ INSERT INTO employees_log SELECT *, current_timestamp FROM upd;
   <para>
    Insert or update new distributors as appropriate.  Assumes a unique
    index has been defined that constrains values appearing in the
-   <literal>did</literal> column.  Note that the special
-   <varname>excluded</varname> table is used to reference values originally
+   <literal>did</literal> column.  Note that the name
+   <varname>excluded</varname> is used to reference values originally
    proposed for insertion:
 <programlisting>
 INSERT INTO distributors (did, dname)

commit 18206a1b2c81ae280ad9927decc5a975011ffb80
Author: David G. Johnston <david.g.johnston@gmail.com>
Date:   Tue Apr 12 15:30:45 2022 +0000

    doc: Elaborate on the interplay between depends on and drop extension
    
    Per discussion on -general the documentation for the
    ALTER ROUTINE ... DEPENDS ON EXTENSION and DROP EXTENSION doesn't
    clearly indicate that these dependent routines are treated in a
    similar manner to the extension's owned objects when it comes to
    using RESTRICT mode drop: namely their presence doesn't force
    the drop command to abort.  Clear that up.

diff --git a/doc/src/sgml/ref/alter_function.sgml b/doc/src/sgml/ref/alter_function.sgml
index 0ee756a94d..4597b4a4bb 100644
--- a/doc/src/sgml/ref/alter_function.sgml
+++ b/doc/src/sgml/ref/alter_function.sgml
@@ -160,8 +160,10 @@ ALTER FUNCTION <replaceable>name</replaceable> [ ( [ [ <replaceable class="param
      <para>
       This form marks the function as dependent on the extension, or no longer
       dependent on that extension if <literal>NO</literal> is specified.
-      A function that's marked as dependent on an extension is automatically
-      dropped when the extension is dropped.
+      A function that's marked as dependent on an extension is dropped when the
+      extension is dropped, even if cascade is not specified.
+      dependency checking in restrict mode <xref linkend="sql-dropextension"/>.
+      A function can depend upon multiple extensions, and will be dropped when
+      any one of those extensions is dropped.
      </para>
     </listitem>
    </varlistentry>
diff --git a/doc/src/sgml/ref/alter_procedure.sgml b/doc/src/sgml/ref/alter_procedure.sgml
index 033fda92ee..fe835acccf 100644
--- a/doc/src/sgml/ref/alter_procedure.sgml
+++ b/doc/src/sgml/ref/alter_procedure.sgml
@@ -147,7 +147,12 @@ ALTER PROCEDURE <replaceable>name</replaceable> [ ( [ [ <replaceable class="para
     <term><replaceable class="parameter">extension_name</replaceable></term>
     <listitem>
      <para>
-      The name of the extension that the procedure is to depend on.
+      This form marks the procedure as dependent on the extension, or no longer
+      dependent on that extension if <literal>NO</literal> is specified.
+      A procedure that's marked as dependent on an extension is dropped when the
+      extension is dropped, even if cascade is not specified.
+      A procedure can depend upon multiple extensions, and will be dropped when
+      any one of those extensions is dropped.
      </para>
     </listitem>
    </varlistentry>
diff --git a/doc/src/sgml/ref/drop_extension.sgml b/doc/src/sgml/ref/drop_extension.sgml
index 5e507dec92..ec5f7bc4f7 100644
--- a/doc/src/sgml/ref/drop_extension.sgml
+++ b/doc/src/sgml/ref/drop_extension.sgml
@@ -30,7 +30,9 @@ DROP EXTENSION [ IF EXISTS ] <replaceable class="parameter">name</replaceable> [
 
   <para>
    <command>DROP EXTENSION</command> removes extensions from the database.
-   Dropping an extension causes its component objects to be dropped as well.
+   Dropping an extension causes its component objects, and other explicitly
+   dependent routines (see <xref linkend="sql-alterroutine"/>,
+   the depends on extension action), to be dropped as well.
   </para>
 
   <para>
@@ -77,9 +79,10 @@ DROP EXTENSION [ IF EXISTS ] <replaceable class="parameter">name</replaceable> [
     <term><literal>RESTRICT</literal></term>
     <listitem>
      <para>
-      Refuse to drop the extension if any objects depend on it (other than
-      its own member objects and other extensions listed in the same
-      <command>DROP</command> command).  This is the default.
+      For each extension, refuse to drop anything if any objects (other than the
+      extensions listed) depend on it.  However, its own member objects, and routines
+      that are explicitly dependent on this extension, are skipped.
+      This is the default.
      </para>
     </listitem>
    </varlistentry>