Received: from maia.hub.org (unknown [200.46.208.211])
	by mail.postgresql.org (Postfix) with ESMTP id 214C26329D9
	for <pgsql-docs-postgresql.org@mail.postgresql.org>;
	Fri, 26 Feb 2010 20:01:26 -0400 (AST)
Received: from mail.postgresql.org ([200.46.204.86])
	by maia.hub.org (mx1.hub.org [200.46.208.211]) (amavisd-maia,
	port 10024) with ESMTP id 12212-09 for
	<pgsql-docs-postgresql.org@mail.postgresql.org>;
	Sat, 27 Feb 2010 00:01:08 +0000 (UTC)
X-Greylist: from auto-whitelisted by SQLgrey-1.7.6
Received: from momjian.us (momjian.us [70.90.9.53])
	by mail.postgresql.org (Postfix) with ESMTP id A524E6322DD
	for <pgsql-docs@postgresql.org>; Fri, 26 Feb 2010 20:01:13 -0400 (AST)
Received: (from bruce@localhost) by momjian.us (8.11.6/8.11.6) id
 o1R01C027987;
	Fri, 26 Feb 2010 19:01:12 -0500 (EST)
From: Bruce Momjian <bruce@momjian.us>
Message-Id: <201002270001.o1R01C027987@momjian.us>
Subject: Re: CREATE FUNCTION reference page's Notes section is
	getting out of hand
In-Reply-To: <10726.1266108979@sss.pgh.pa.us>
To: Tom Lane <tgl@sss.pgh.pa.us>
Date: Fri, 26 Feb 2010 19:01:12 -0500 (EST)
CC: pgsql-docs@postgresql.org
X-Mailer: ELM [version 2.4ME+ PL124 (25)]
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="ELM1267228872-12797-3_"
Content-Transfer-Encoding: 7bit
X-Virus-Scanned: Maia Mailguard 1.0.1
X-Spam-Status: No, hits=-1.635 tagged_above=-10 required=5 tests=AWL=-0.525,
	BAYES_05=-1.11
X-Spam-Level: 
X-Archive-Number: 201002/47
X-Sequence-Number: 5363


--ELM1267228872-12797-3_
Content-Transfer-Encoding: 7bit
Content-Type: text/plain; charset="US-ASCII"

Tom Lane wrote:
> I observe that the Notes section here
> http://developer.postgresql.org/pgdocs/postgres/sql-createfunction.html
> has turned into a disorganized laundry list of unrelated items,
> ranging from quite-subtle issues to barely-useful-even-to-novices
> advice (do we really need "Use DROP FUNCTION to remove user-defined
> functions" here?  Especially given the See Also link later on?).
> 
> I don't have an immediate proposal what to do about it, but it seems
> like it could use some effort.  Any thoughts?

Yea, it is hard to read.  What I did was to move some items up into
their proper sections, and add an "Overloading" heading.  You can see
the results here:

	http://momjian.us/tmp/pgsql/sql-createfunction.html

and a patch is attached.

-- 
  Bruce Momjian  <bruce@momjian.us>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com
  PG East:  http://www.enterprisedb.com/community/nav-pg-east-2010.do
  + If your life is a hard drive, Christ can be your backup. +

--ELM1267228872-12797-3_
Content-Transfer-Encoding: 7bit
Content-Type: text/x-diff
Content-Disposition: inline; filename="/pgpatches/func"

Index: doc/src/sgml/ref/create_function.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v
retrieving revision 1.91
diff -c -c -r1.91 create_function.sgml
*** doc/src/sgml/ref/create_function.sgml	25 Feb 2010 22:24:00 -0000	1.91
--- doc/src/sgml/ref/create_function.sgml	26 Feb 2010 23:58:55 -0000
***************
*** 46,51 ****
--- 46,55 ----
     <command>CREATE FUNCTION</command> defines a new function.
     <command>CREATE OR REPLACE FUNCTION</command> will either create a
     new function, or replace an existing definition.
+    To be able to define a function, the user must have the
+    <literal>USAGE</literal> privilege on the language.
+   </para>
+ 
    </para>
  
    <para>
***************
*** 70,75 ****
--- 74,87 ----
    </para>
  
    <para>
+    When <command>CREATE OR REPLACE FUNCTION</> is used to replace an
+    existing function, the ownership and permissions of the function
+    do not change.  All other function properties are assigned the
+    values specified or implied in the command.  You must own the function
+    to replace it (this includes being a member of the owning role).
+   </para>
+ 
+   <para>
     If you drop and then recreate a function, the new function is not
     the same entity as the old; you will have to drop existing rules, views,
     triggers, etc. that refer to the old function.  Use
***************
*** 401,406 ****
--- 413,430 ----
        </para>
  
        <para>
+        If a <literal>SET</> clause is attached to a function, then
+        the effects of a <command>SET LOCAL</> command executed inside the
+        function for the same variable are restricted to the function: the
+        configuration parameter's prior value is still restored at function exit.
+        However, an ordinary
+        <command>SET</> command (without <literal>LOCAL</>) overrides the
+        <literal>SET</> clause, much as it would do for a previous <command>SET
+        LOCAL</> command: the effects of such a command will persist after
+        function exit, unless the current transaction is rolled back.
+       </para>
+    
+       <para>
         See <xref linkend="sql-set" endterm="sql-set-title"> and
         <xref linkend="runtime-config">
         for more information about allowed parameter names and values.
***************
*** 417,422 ****
--- 441,455 ----
         language.  It can be an internal function name, the path to an
         object file, an SQL command, or text in a procedural language.
        </para>
+ 
+       <para>
+        It is often helpful to use dollar quoting (see <xref
+        linkend="sql-syntax-dollar-quoting">) to write the function definition
+        string, rather than the normal single quote syntax.  Without dollar
+        quoting, any single quotes or backslashes in the function definition must
+        be escaped by doubling them.
+       </para>
+ 
       </listitem>
      </varlistentry>
  
***************
*** 436,441 ****
--- 469,482 ----
         language source code.  If the link symbol is omitted, it is assumed
         to be the same as the name of the SQL function being defined.
        </para>
+ 
+       <para>
+        When repeated <command>CREATE FUNCTION</command> calls refer to
+        the same object file, the file is only loaded once per session.
+        To unload and
+        reload the file (perhaps during development), start a new session.
+       </para>
+ 
       </listitem>
      </varlistentry>
  
***************
*** 479,501 ****
  
   </refsect1>
  
!  <refsect1 id="sql-createfunction-notes">
!   <title>Notes</title>
! 
!    <para>
!     Refer to <xref linkend="xfunc"> for further information on writing
!     functions.
!    </para>
  
!    <para>
!     The full <acronym>SQL</acronym> type syntax is allowed for
!     input arguments and return value. However, some details of the
!     type specification (e.g., the precision field for
!     type <type>numeric</type>) are the responsibility of the
!     underlying function implementation and are silently swallowed
!     (i.e., not recognized or
!     enforced) by the <command>CREATE FUNCTION</command> command.
!    </para>
  
     <para>
      <productname>PostgreSQL</productname> allows function
--- 520,532 ----
  
   </refsect1>
  
!  <para>
!   Refer to <xref linkend="xfunc"> for further information on writing
!   functions.
!  </para>
  
!  <refsect1 id="sql-createfunction-overloading">
!   <title>Overloading</title>
  
     <para>
      <productname>PostgreSQL</productname> allows function
***************
*** 529,578 ****
      function should be called.
     </para>
  
!    <para>
!     When repeated <command>CREATE FUNCTION</command> calls refer to
!     the same object file, the file is only loaded once per session.
!     To unload and
!     reload the file (perhaps during development), start a new session.
!    </para>
! 
!    <para>
!     Use <xref linkend="sql-dropfunction"
!     endterm="sql-dropfunction-title"> to remove user-defined
!     functions.
!    </para>
! 
!    <para>
!     It is often helpful to use dollar quoting (see <xref
!     linkend="sql-syntax-dollar-quoting">) to write the function definition
!     string, rather than the normal single quote syntax.  Without dollar
!     quoting, any single quotes or backslashes in the function definition must
!     be escaped by doubling them.
!    </para>
! 
!    <para>
!     If a <literal>SET</> clause is attached to a function, then
!     the effects of a <command>SET LOCAL</> command executed inside the
!     function for the same variable are restricted to the function: the
!     configuration parameter's prior value is still restored at function exit.
!     However, an ordinary
!     <command>SET</> command (without <literal>LOCAL</>) overrides the
!     <literal>SET</> clause, much as it would do for a previous <command>SET
!     LOCAL</> command: the effects of such a command will persist after
!     function exit, unless the current transaction is rolled back.
!    </para>
  
!    <para>
!     To be able to define a function, the user must have the
!     <literal>USAGE</literal> privilege on the language.
!    </para>
  
     <para>
!     When <command>CREATE OR REPLACE FUNCTION</> is used to replace an
!     existing function, the ownership and permissions of the function
!     do not change.  All other function properties are assigned the
!     values specified or implied in the command.  You must own the function
!     to replace it (this includes being a member of the owning role).
     </para>
  
     <para>
--- 560,578 ----
      function should be called.
     </para>
  
!  </refsect1>
  
!  <refsect1 id="sql-createfunction-notes">
!   <title>Notes</title>
  
     <para>
!     The full <acronym>SQL</acronym> type syntax is allowed for
!     input arguments and return value. However, some details of the
!     type specification (e.g., the precision field for
!     type <type>numeric</type>) are the responsibility of the
!     underlying function implementation and are silently swallowed
!     (i.e., not recognized or
!     enforced) by the <command>CREATE FUNCTION</command> command.
     </para>
  
     <para>

--ELM1267228872-12797-3_--