Re: Dollar Quoting doc patch--resend. - Mailing list pgsql-patches

On 5-May-04, at 2:26 AM, David Fetter wrote:
> Here it is :)

Looks good for the most part. A few minor quibbles / suggestions:

- Where an example uses double-quotes in a function body, we ought to
change the example to use dollar quoting -- but if no doubled-quotes
are used, I think it's better to just stick with single quotes. You've
needlessly converted a few function bodies to use dollar quotes in
violation of this principle -- please revert them

- Can you flesh out the syntax.sgml modifications? e.g. The term
"dollar quoting", or what example a "dollar quote" consists of, is
never defined. You might want to add a new subsection to allow <xref>s
from elsewhere (and add some <xref>s, too)

- Adding a reference to dollar quoting in the CREATE FUNCTION ref page
would be a good idea

- You also ought to update xfunc.sgml (circa line 105 at least)

- Specific comments:

*** doc/src/sgml/plperl.sgml    14 Dec 2003 00:10:32 -0000    2.22
--- doc/src/sgml/plperl.sgml    27 Apr 2004 21:10:23 -0000
***************
*** 47,53 ****
      To create a function in the PL/Perl language, use the standard
syntax:
   <programlisting>
! CREATE FUNCTION <replaceable>funcname</replaceable>
(<replaceable>argument-types</replaceable>) RETURNS
<replaceable>return-type</replaceable> AS '
       # PL/Perl function body
! ' LANGUAGE plperl;
   </programlisting>
      The body of the function is ordinary Perl code.
--- 47,54 ----
      To create a function in the PL/Perl language, use the standard
syntax:
   <programlisting>
! CREATE FUNCTION <replaceable>funcname</replaceable>
! (<replaceable>argument-types</replaceable>) RETURNS
<replaceable>return-type</replaceable> AS $dollar_quote$
       # PL/Perl function body
! $dollar_quote$ LANGUAGE plperl;
   </programlisting>
      The body of the function is ordinary Perl code.

If you're going to make this change, you ought similar changes to other
CREATE FUNCTION syntax definitions (e.g. the CREATE FUNCTION reference
page) for consistency. Not sure if it's the right thing to do to begin
with, though...

*** doc/src/sgml/plpgsql.sgml    26 Mar 2004 03:18:28 -0000    1.37
--- doc/src/sgml/plpgsql.sgml    27 Apr 2004 21:10:24 -0000
***************
*** 979,982 ****
--- 983,991 ----

       <para>
+     You <emphasis>were</emphasis> using dollar quoting to make the
+     function body, weren't you?
+     </para>
+
+     <para>
        To test for whether a record/row result is null, you can use the
        <literal>IS NULL</literal> conditional.  There is, however, no

This ought to be phrased less colloquially.

***************
*** 2654,2671 ****
       v_path := NULL;
       v_query := NULL;
!     a_pos1 := instr(v_url, '//');

       IF a_pos1 = 0 THEN
           RETURN;
       END IF;
!     a_pos2 := instr(v_url, '/', a_pos1 + 2);
       IF a_pos2 = 0 THEN
           v_host := substr(v_url, a_pos1 + 2);
!         v_path := '/';
           RETURN;
       END IF;

       v_host := substr(v_url, a_pos1 + 2, a_pos2 - a_pos1 - 2);
!     a_pos1 := instr(v_url, '?', a_pos2 + 1);

       IF a_pos1 = 0 THEN
--- 2698,2715 ----
       v_path := NULL;
       v_query := NULL;
!     a_pos1 := instr(v_url, ''//'');

       IF a_pos1 = 0 THEN
           RETURN;
       END IF;
!     a_pos2 := instr(v_url, ''/'', a_pos1 + 2);
       IF a_pos2 = 0 THEN
           v_host := substr(v_url, a_pos1 + 2);
!         v_path := ''/'';
           RETURN;
       END IF;

       v_host := substr(v_url, a_pos1 + 2, a_pos2 - a_pos1 - 2);
!     a_pos1 := instr(v_url, ''?'', a_pos2 + 1);

       IF a_pos1 = 0 THEN

That's an Oracle example function, so I think the existing use of
quotes is fine.

-Neil