Doc: improve introductory information about procedures.

Clarify the discussion in "User-Defined Procedures", by laying out
the key differences between functions and procedures in a bulleted
list.  Notably, this avoids burying the lede about procedures being
able to do transaction control.  Make the back-link in the CREATE
FUNCTION reference page more prominent, and add one in CREATE
PROCEDURE.

Per gripe from Guyren Howe.  Thanks to David Johnston for discussion.

Discussion: https://postgr.es/m/BYAPR03MB4903C53A8BB7EFF5EA289674A6949@BYAPR03MB4903.namprd03.prod.outlook.com

diff --git a/doc/src/sgml/ref/create_function.sgml b/doc/src/sgml/ref/create_function.sgml
index 3c1eaea651cbf04a19ec111774067cd87476d6e6..f1001615f4aec26ef2911fd1f286aa14f81f6b84 100644 (file)
--- 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 USAGE
    privilege on the argument types and the return type.
   
+
+  
+   Refer to  for further information on writing
+   functions.
+  
  
 
  
@@ -578,12 +583,6 @@ CREATE [ OR REPLACE ] FUNCTION
     
 
    
-
-   
-    Refer to  for further information on writing
-    functions.
-   
-
  
 
  
@@ -661,8 +660,7 @@ CREATE FUNCTION foo(int, int default 42) ...
   Examples
 
   
-   Here are some trivial examples to help you get started.  For more
-   information and examples, see .
+   Add two integers using a SQL function:
 
 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 e258eca5ceeae267efecd0ab6b68a251f84479b5..6dbc01271941f9bb8144d7f3fc1e1edfac517890 100644 (file)
--- 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 USAGE
    privilege on the argument types.
   
+
+  
+   Refer to  for further information on writing
+   procedures.
+  
  
 
  

diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml
index 2863f7c20657fb757b84c8b9fca736f68ab35bde..41bcc5b79ddb0e1861543125a29f5bb0cc931d82 100644 (file)
--- a/doc/src/sgml/xfunc.sgml
+++ b/doc/src/sgml/xfunc.sgml
@@ -63,7 +63,8 @@
 
   
    Throughout this chapter, it can be useful to look at the reference
-   page of the  command to
+   page of the CREATE
+   FUNCTION command to
    understand the examples better.  Some examples from this chapter
    can be found in funcs.sql and
    funcs.c in the src/tutorial
@@ -81,21 +82,55 @@
   
 
    
-    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 CALL command.  If the CALL 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:
+
+    
+     
+      
+       Procedures are defined with
+       the CREATE
+       PROCEDURE command, not CREATE
+       FUNCTION.
+      
+     
+     
+      
+       Procedures do not return a function value; hence CREATE
+       PROCEDURE lacks a RETURNS clause.
+       However, procedures can instead return data to their callers via
+       output parameters.
+      
+     
+     
+      
+       While a function is called as part of a query or DML command, a
+       procedure is called in isolation using
+       the CALL command.
+      
+     
+     
+      
+       A procedure can commit or roll back transactions during its
+       execution (then automatically beginning a new transaction), so long
+       as the invoking CALL command is not part of an
+       explicit transaction block.  A function cannot do that.
+      
+     
+     
+      
+       Certain function attributes, such as strictness, don't apply to
+       procedures.  Those attributes control how the function is
+       used in a query, which isn't relevant to procedures.
+      
+     
+    
    
 
    
-    The explanations on how to define user-defined functions in the rest of
-    this chapter apply to procedures as well, except that
-    the CREATE PROCEDURE 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.