"David G. Johnston" <[email protected]> writes:
> On Tue, Mar 9, 2021 at 4:50 PM Tom Lane <[email protected]> wrote:
>> Would it be better
>> to turn the para into a bulleted list, which we could introduce with
>> "The key differences are:" ?
> Indeed, reworking the rest of the paragraph around that introduction would
> be much better.
v2 attached.
regards, tom lane
diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index 9d41967ad3..9242c54329 100644
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -1959,7 +1959,8 @@ SELECT * FROM get_available_flightid(CURRENT_DATE);
or <command>DO</command> block can call a procedure
using <command>CALL</command>. Output parameters are handled
differently from the way that <command>CALL</command> works in plain
- SQL. Each <literal>INOUT</literal> parameter of the procedure must
+ SQL. Each <literal>OUT</literal> or <literal>INOUT</literal>
+ parameter of the procedure must
correspond to a variable in the <command>CALL</command> statement, and
whatever the procedure returns is assigned back to that variable after
it returns. For example:
diff --git a/doc/src/sgml/ref/create_function.sgml b/doc/src/sgml/ref/create_function.sgml
index 3c1eaea651..f1001615f4 100644
--- a/doc/src/sgml/ref/create_function.sgml
+++ b/doc/src/sgml/ref/create_function.sgml
@@ -100,6 +100,11 @@ CREATE [ OR REPLACE ] FUNCTION
To be able to create a function, you must have <literal>USAGE</literal>
privilege on the argument types and the return type.
</para>
+
+ <para>
+ Refer to <xref linkend="xfunc"/> for further information on writing
+ functions.
+ </para>
</refsect1>
<refsect1>
@@ -578,12 +583,6 @@ CREATE [ OR REPLACE ] FUNCTION
</varlistentry>
</variablelist>
-
- <para>
- Refer to <xref linkend="xfunc"/> for further information on writing
- functions.
- </para>
-
</refsect1>
<refsect1 id="sql-createfunction-overloading">
@@ -661,8 +660,7 @@ CREATE FUNCTION foo(int, int default 42) ...
<title>Examples</title>
<para>
- Here are some trivial examples to help you get started. For more
- information and examples, see <xref linkend="xfunc"/>.
+ Add two integers using a SQL function:
<programlisting>
CREATE FUNCTION add(integer, integer) RETURNS integer
AS 'select $1 + $2;'
diff --git a/doc/src/sgml/ref/create_procedure.sgml b/doc/src/sgml/ref/create_procedure.sgml
index e258eca5ce..6dbc012719 100644
--- a/doc/src/sgml/ref/create_procedure.sgml
+++ b/doc/src/sgml/ref/create_procedure.sgml
@@ -76,6 +76,11 @@ CREATE [ OR REPLACE ] PROCEDURE
To be able to create a procedure, you must have <literal>USAGE</literal>
privilege on the argument types.
</para>
+
+ <para>
+ Refer to <xref linkend="xproc"/> for further information on writing
+ procedures.
+ </para>
</refsect1>
<refsect1>
diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml
index 2863f7c206..325ce9222a 100644
--- a/doc/src/sgml/xfunc.sgml
+++ b/doc/src/sgml/xfunc.sgml
@@ -81,21 +81,55 @@
</indexterm>
<para>
- A procedure is a database object similar to a function. The difference is
- that a procedure does not return a value, so there is no return type
- declaration. While a function is called as part of a query or DML
- command, a procedure is called in isolation using
- the <link linkend="sql-call"><command>CALL</command></link> command. If the <command>CALL</command> command is not
- part of an explicit transaction, a procedure in many server-side
- languages can commit, rollback, and begin new transactions during
- its execution, which is not possible in functions.
+ A procedure is a database object similar to a function.
+ The key differences are:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Procedures are defined with
+ the <link linkend="sql-createprocedure"><command>CREATE
+ PROCEDURE</command></link> command, not <command>CREATE
+ FUNCTION</command>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Procedures do not return a function value; hence <command>CREATE
+ PROCEDURE</command> lacks a <literal>RETURNS</literal> clause.
+ However, procedures can instead return data to their callers via
+ output parameters.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ While a function is called as part of a query or DML command, a
+ procedure is called in isolation using
+ the <link linkend="sql-call"><command>CALL</command></link> command.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If the invoking <command>CALL</command> command is not part of an
+ explicit transaction block, a procedure can commit or roll back
+ transactions (then automatically beginning a new transaction)
+ during its execution, which a function cannot do.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Certain function attributes such as strictness don't apply to
+ procedures, because those attributes control how the function is
+ used in a query, which isn't relevant to procedures.
+ </para>
+ </listitem>
+ </itemizedlist>
</para>
<para>
- The explanations on how to define user-defined functions in the rest of
- this chapter apply to procedures as well, except that
- the <link linkend="sql-createprocedure"><command>CREATE PROCEDURE</command></link> command is used instead, there is
- no return type, and some other features such as strictness don't apply.
+ The explanations in the following sections about how to define
+ user-defined functions apply to procedures as well, except for the
+ points made above.
</para>
<para>
