commit 678834d2fc1d74710ca36b075be0989832e15cec
Author: David G. Johnston <david.g.johnston@gmail.com>
Date:   Fri Oct 2 20:02:00 2020 +0000

    Minor cleanup and rewording of plpgsql docs

diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index 815912666d..4af66a637c 100644
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -856,7 +856,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
@@ -945,11 +945,13 @@ my_record.user_id := 20;
     </para>
 
     <para>
-     Any <application>PL/pgSQL</application> variable name appearing
-     in the command text is treated as a parameter, and then the
+     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"/>.
+     If the SQL command being executed is incapable of returning a result
+     it does not accept query parameters.
     </para>
 
     <para>
@@ -2507,7 +2509,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"/>.
@@ -4583,9 +4585,9 @@ 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, identifiers 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>
@@ -4597,13 +4599,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
@@ -5253,13 +5248,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