commit da8f0114fc9a661c001e49df540ccaa35dbbdb29
Author: David G. Johnston <david.g.johnston@gmail.com>
Date:   Mon Nov 30 03:17:26 2020 +0000

    Minor cleanup and rewording of plpgsql docs

diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index 9ec168b0c4..ffe124ab54 100644
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -894,7 +894,7 @@ SELECT <replaceable>expression</replaceable>
 </synopsis>
      to the main SQL engine.  While forming the <command>SELECT</command> command,
      any occurrences of <application>PL/pgSQL</application> variable names
-     are replaced by parameters, as discussed in detail in
+     are replaced by query parameters, as discussed in detail in
      <xref linkend="plpgsql-var-subst"/>.
      This allows the query plan for the <command>SELECT</command> to
      be prepared just once and then reused for subsequent
@@ -976,15 +976,23 @@ my_record.user_id := 20;
     <title>Executing a Command with No Result</title>
 
     <para>
-     For any SQL command that does not return rows, for example
-     <command>INSERT</command> without a <literal>RETURNING</literal> clause, you can
-     execute the command within a <application>PL/pgSQL</application> function
-     just by writing the command.
+     The utility SQL commands, which are incapable of returning results,
+     (e.g., DDL commands like CREATE TABLE and DROP TYPE,
+     and the environment changing command SET), are executed just by
+     writing the command.
     </para>
 
     <para>
-     Any <application>PL/pgSQL</application> variable name appearing
-     in the command text is treated as a parameter, and then the
+     You can also execute a <command>DELETE</command>, <command>INSERT</command>,
+     or <command>UPDATE</command> SQL command, without a <literal>RETURNING</literal>
+     clause, just by writing the command.  Adding the <literal>RETURNING</literal>
+     makes the command behave like <command>SELECT</command>, which is described
+     in the next section.
+    </para>
+
+    <para>
+     For the non-utility commands, any <application>PL/pgSQL</application> variables
+     appearing in the command text are replaced by query parameters, and then the
      current value of the variable is provided as the parameter value
      at run time.  This is exactly like the processing described earlier
      for expressions; for details see <xref linkend="plpgsql-var-subst"/>.
@@ -2545,7 +2553,7 @@ $$ LANGUAGE plpgsql;
     </para>
 
     <para>
-     <application>PL/pgSQL</application> variables are substituted into the query text,
+     <application>PL/pgSQL</application> variables are converted into query parameters,
      and the query plan is cached for possible re-use, as discussed in
      detail in <xref linkend="plpgsql-var-subst"/> and
      <xref linkend="plpgsql-plan-caching"/>.
@@ -4621,9 +4629,10 @@ CREATE EVENT TRIGGER snitch ON ddl_command_start EXECUTE FUNCTION snitch();
     SQL statements and expressions within a <application>PL/pgSQL</application> function
     can refer to variables and parameters of the function.  Behind the scenes,
     <application>PL/pgSQL</application> substitutes query parameters for such references.
-    Parameters will only be substituted in places where a parameter or
-    column reference is syntactically allowed.  As an extreme case, consider
-    this example of poor programming style:
+    Query parameters will only be substituted in places where syntactically allowed
+    (in particular, SQL identifiers - such as schema, table, and column names - can never
+    be replaced with a query parameter.)
+    As an extreme case, consider this example of poor programming style:
 <programlisting>
 INSERT INTO foo (foo) VALUES (foo);
 </programlisting>
@@ -4635,13 +4644,6 @@ INSERT INTO foo (foo) VALUES (foo);
     variable.
    </para>
 
-   <note>
-    <para>
-     <productname>PostgreSQL</productname> versions before 9.0 would try
-     to substitute the variable in all three cases, leading to syntax errors.
-    </para>
-   </note>
-
    <para>
     Since the names of variables are syntactically no different from the names
     of table columns, there can be ambiguity in statements that also refer to
@@ -5291,13 +5293,14 @@ HINT:  Make sure the query returns the exact list of columns.
     <itemizedlist>
      <listitem>
       <para>
-       If a name used in a SQL command could be either a column name of a
-       table or a reference to a variable of the function,
-       <application>PL/SQL</application> treats it as a column name.  This corresponds
-       to <application>PL/pgSQL</application>'s
+       If a name used in a SQL command matches a known column name and also
+       a named variable within the function,
+       <application>PL/SQL</application> treats it as a column name.
+       By default, <application>PL/pgSQL</application> will treat it as a variable,
+       but one can specify  
        <literal>plpgsql.variable_conflict</literal> = <literal>use_column</literal>
-       behavior, which is not the default,
-       as explained in <xref linkend="plpgsql-var-subst"/>.
+       (see <xref linkend="plpgsql-var-subst"/> for specifics)
+       to change the behavior to match <application>PL/SQL</application>.
        It's often best to avoid such ambiguities in the first place,
        but if you have to port a large amount of code that depends on
        this behavior, setting <literal>variable_conflict</literal> may be the