Re: CREATE FUNCTION reference page's Notes section is getting out of hand

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(at)momjian(dot)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(at)postgresql(dot)org)
> To make changes to your subscription:
> http://www.postgresql.org/mailpref/pgsql-docs

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

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