Received: from maia.hub.org (unknown [200.46.208.211])
	by mail.postgresql.org (Postfix) with ESMTP id 53EF0633C29
	for <pgsql-docs-postgresql.org@mail.postgresql.org>;
	Tue,  2 Mar 2010 23:14:33 -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 90777-09 for
	<pgsql-docs-postgresql.org@mail.postgresql.org>;
	Wed,  3 Mar 2010 03:14:13 +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 69D2D63297D
	for <pgsql-docs@postgresql.org>; Tue,  2 Mar 2010 23:14:22 -0400 (AST)
Received: (from bruce@localhost) by momjian.us (8.11.6/8.11.6) id
 o233EIX12422;
	Tue, 2 Mar 2010 22:14:18 -0500 (EST)
From: Bruce Momjian <bruce@momjian.us>
Message-Id: <201003030314.o233EIX12422@momjian.us>
Subject: Re: CREATE FUNCTION reference page's Notes section is
	getting out of hand
In-Reply-To: <201002270001.o1R01C027987@momjian.us>
To: Bruce Momjian <bruce@momjian.us>
Date: Tue, 2 Mar 2010 22:14:18 -0500 (EST)
CC: Tom Lane <tgl@sss.pgh.pa.us>, pgsql-docs@postgresql.org
X-Mailer: ELM [version 2.4ME+ PL124 (25)]
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Type: text/plain; charset="US-ASCII"
X-Virus-Scanned: Maia Mailguard 1.0.1
X-Spam-Status: No, hits=-1.066 tagged_above=-10 required=5 tests=AWL=-1.067,
	BAYES_50=0.001
X-Spam-Level: 
X-Archive-Number: 201003/1
X-Sequence-Number: 5366

Bruce Momjian wrote:
> 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.
> 

Applied.

---------------------------------------------------------------------------


> -- 
>   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. +

[ text/x-diff is unsupported, treating like TEXT/PLAIN ]

> 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>

> 
> -- 
> Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
> To make changes to your subscription:
> http://www.postgresql.org/mailpref/pgsql-docs

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

  PG East:  http://www.enterprisedb.com/community/nav-pg-east-2010.do