Date: Fri, 21 Aug 2020 18:52:14 -0400
From: Bruce Momjian <bruce@momjian.us>
To: Robin Abbi <robin.abbi@downley.net>
Cc: Dave Cramer <davecramer@postgres.rocks>,
	pgsql-docs@lists.postgresql.org
Subject: Re: Procedures
Message-ID: <20200821225214.GJ13363@momjian.us>
References: <159653722937.654.5519018237996991238@wrigleys.postgresql.org>
 <20200806001758.GA29874@momjian.us>
 <CADK3HH+cyx-aFnf8Tzra2qtBwD+e-k-cpnrjXhX9G9_-MKJj4A@mail.gmail.com>
 <CAGmg_NX327KKVuJmbWZD=pGutYFxzZjX1rU+3ji8UuX=8ONn9Q@mail.gmail.com>
 <20200806221052.GA23547@momjian.us>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="V88s5gaDVPzZ0KCq"
Content-Disposition: inline
In-Reply-To: <20200806221052.GA23547@momjian.us>
User-Agent: Mutt/1.10.1 (2018-07-13)
Precedence: bulk


--V88s5gaDVPzZ0KCq
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline

On Thu, Aug  6, 2020 at 06:10:52PM -0400, Bruce Momjian wrote:
> On Thu, Aug  6, 2020 at 02:30:55PM +0100, Robin Abbi wrote:
> > PostgreSQL went as far as release 10 without procedures.
> > Some third party resources written before 11 loosely conflate procedures with
> > functions.
> > Some third party resources written before 11 accurately state PostgreSQL has
> > functions but not procedures.
> > Referring to the PostgreSQL docs for 11 on, procedures have been added.
> > 
> > For someone like me, coming to the subject without much of a hinterland other
> > than googling around, it seemed clear that there was a motivating case that
> > caused Procedures to be added to PostgreSQL, but I was not sufficiently
> > familiar with the domain to be able to readily intuit what it might have been.
> > 
> > For example, Procedures say they have no return value, yet Functions can return
> > void. Not the same I agree, but I wouldn't be aware in which circumstances it
> > mattered.
> > 
> > For me, perhaps the most useful thing would have been a small example
> > highlighting the essential thing(s) that procedures can do that functions could
> > not.
> 
> Agreed, this doc area needs help.

I developed the attached patach for this.  Is this sufficient?

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EnterpriseDB                             https://enterprisedb.com

  The usefulness of a cup is in its emptiness, Bruce Lee


--V88s5gaDVPzZ0KCq
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment; filename="proc.diff"

diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml
index 6de464c654..0b52feffe5 100644
--- a/doc/src/sgml/xfunc.sgml
+++ b/doc/src/sgml/xfunc.sgml
@@ -83,7 +83,8 @@
    <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
+    declaration.  Procedures can also begin and commit transactions.
+    While a function is called as part of a query or DML
     command, a procedure is called explicitly using
     the <xref linkend="sql-call"/> statement.
    </para>

--V88s5gaDVPzZ0KCq--