Dollar Quoting doc patch--resend.

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

Neil Conway wrote:

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

I disagree. I think swiching between single quote and $$ based on the
content is just too confusing. I would just use $$ in all cases unless
$$ appears in the function (which should be rare), in which case I would
use $quote$ or something generic. I am also not a fan of using
$something$ that varies based on the type of function.

-- 
  Bruce Momjian                        |  http://candle.pha.pa.us
  pgman@candle.pha.pa.us               |  (610) 359-1001
  +  If your life is a hard drive,     |  13 Roberts Road
  +  Christ can be your backup.        |  Newtown Square, Pennsylvania 19073

On Wed, May 05, 2004 at 10:42:56AM -0400, Bruce Momjian wrote:

Neil Conway wrote:

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

I disagree. I think swiching between single quote and $$ based on
the content is just too confusing. I would just use $$ in all cases
unless $$ appears in the function (which should be rare), in which
case I would use $quote$ or something generic. I am also not a fan
of using $something$ that varies based on the type of function.

You folks have commit privs, so please settle on something.

Here's $.01 worth:

It ought to be pretty clear in each example that the stuff between the
$'s can be varied.

Another $.01:

Examples are in distressingly short and cloudy supply across
PostgreSQL docs. This appears to reflect the Greek tradition of
inquiry, as opposed (in this case) to the Babylonian one Richard
Feynman advocated, cf. <http://www.jefallbright.net/node/view/2062&gt;.

I am doing what I can to correct this deficiency, and encourage others
to join me in this effort.

OK, that's my $.02 :)

Cheers,
D
--
David Fetter david@fetter.org http://fetter.org/
phone: +1 510 893 6100 mobile: +1 415 235 3778

Remember to vote!

David Fetter wrote:

You folks have commit privs, so please settle on something.

Here's $.01 worth:

It ought to be pretty clear in each example that the stuff between the
$'s can be varied.

Yes, we need to show that it can be varied, but when we are trying to
illustrate another concept, we should show examples that highlight
that concept, not add additional complexity with showing we can put a
tag between $$. My guess is that if we show $tag$ all the time, folks
will not know that they can just do $$, which I think is the most
common usage for dollar quoting.

With shell HERE documents, you have to supply a tag, while with $$ you
do not, so I think would be very easy for folks to think a tag is
required.

-- 
  Bruce Momjian                        |  http://candle.pha.pa.us
  pgman@candle.pha.pa.us               |  (610) 359-1001
  +  If your life is a hard drive,     |  13 Roberts Road
  +  Christ can be your backup.        |  Newtown Square, Pennsylvania 19073

David Fetter wrote:

On Wed, May 05, 2004 at 10:42:56AM -0400, Bruce Momjian wrote:

Neil Conway wrote:

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

I disagree. I think swiching between single quote and $$ based on
the content is just too confusing. I would just use $$ in all cases
unless $$ appears in the function (which should be rare), in which
case I would use $quote$ or something generic. I am also not a fan
of using $something$ that varies based on the type of function.

You folks have commit privs, so please settle on something.

Here's $.01 worth:

It ought to be pretty clear in each example that the stuff between the
$'s can be varied.

Another $.01:

Examples are in distressingly short and cloudy supply across
PostgreSQL docs. This appears to reflect the Greek tradition of
inquiry, as opposed (in this case) to the Babylonian one Richard
Feynman advocated, cf. <http://www.jefallbright.net/node/view/2062&gt;.

I am doing what I can to correct this deficiency, and encourage others
to join me in this effort.

OK, that's my $.02 :)

My own style, taken from what I use in heredocs, would indicate the kind
of thing enclosed. It's a matter of taste, but I think that style could
help make the examples clearer, expecially as it is most useful when we
have deeply nested stuff.

BTW, my thanks to David for having undertaken the task of doing this docco.

cheers

andrew

On 5-May-04, at 11:32 AM, Bruce Momjian wrote:

Yes, we need to show that it can be varied, but when we are trying to
illustrate another concept, we should show examples that highlight
that concept, not add additional complexity with showing we can put a
tag between $$. My guess is that if we show $tag$ all the time, folks
will not know that they can just do $$, which I think is the most
common usage for dollar quoting.

I don't see the need to include $tag$ in _every_ example: a few
examples of $tag$ rather than $$ plus a clear definition of what a
"dollar quote" is allowed to be should be sufficient to let users know
what they can use, and the rest of the time we ought to use whatever is
syntactically clearest.

-Neil

On 5-May-04, at 10:42 AM, Bruce Momjian wrote:

I disagree. I think swiching between single quote and $$ based on the
content is just too confusing. I would just use $$ in all cases unless
$$ appears in the function (which should be rare), in which case I
would
use $quote$ or something generic.

Well, the function definition in CREATE FUNCTION is a string literal
like any other. Based on the reasoning above, would you argue for using
$$ for every other string literal in the documentation rather than
single quotes? If not, then we're not being consistent anyway, so I
don't find the argument very convincing.

Why not use whatever quoting mechanism is clearest for a particular
example? In some cases that will be single-quotes, in others it will be
dollar quoting via $$, and in still others it will be dollar quoting
via $tag$

-Neil

Neil Conway wrote:

On 5-May-04, at 10:42 AM, Bruce Momjian wrote:

I disagree. I think swiching between single quote and $$ based on the
content is just too confusing. I would just use $$ in all cases unless
$$ appears in the function (which should be rare), in which case I
would
use $quote$ or something generic.

Well, the function definition in CREATE FUNCTION is a string literal
like any other. Based on the reasoning above, would you argue for using
$$ for every other string literal in the documentation rather than
single quotes? If not, then we're not being consistent anyway, so I
don't find the argument very convincing.

Why not use whatever quoting mechanism is clearest for a particular
example? In some cases that will be single-quotes, in others it will be
dollar quoting via $$, and in still others it will be dollar quoting
via $tag$

OK. I am just afraid if we show 4 functions, and three use $$, and one
doesn't use single-quotes inside, so we quote with single-quotes, that
it would look strange.

-- 
  Bruce Momjian                        |  http://candle.pha.pa.us
  pgman@candle.pha.pa.us               |  (610) 359-1001
  +  If your life is a hard drive,     |  13 Roberts Road
  +  Christ can be your backup.        |  Newtown Square, Pennsylvania 19073

On 6-May-04, at 12:41 AM, Bruce Momjian wrote:

OK. I am just afraid if we show 4 functions, and three use $$, and one
doesn't use single-quotes inside, so we quote with single-quotes, that
it would look strange.

Personally I don't think it would look that strange, but maybe that's
just me. Does anyone else want to weigh in here?

-Neil

Neil Conway wrote:

On 6-May-04, at 12:41 AM, Bruce Momjian wrote:

OK. I am just afraid if we show 4 functions, and three use $$, and one
doesn't use single-quotes inside, so we quote with single-quotes, that
it would look strange.

Personally I don't think it would look that strange, but maybe that's
just me. Does anyone else want to weigh in here?

I think the big question is whether single quotes appear in function
bodies so often that we should suggest folks just use $$ all the time.

-- 
  Bruce Momjian                        |  http://candle.pha.pa.us
  pgman@candle.pha.pa.us               |  (610) 359-1001
  +  If your life is a hard drive,     |  13 Roberts Road
  +  Christ can be your backup.        |  Newtown Square, Pennsylvania 19073

On Thu, May 06, 2004 at 12:47:46AM -0400, Bruce Momjian wrote:

Neil Conway wrote:

On 6-May-04, at 12:41 AM, Bruce Momjian wrote:

OK. I am just afraid if we show 4 functions, and three use $$,
and one doesn't use single-quotes inside, so we quote with
single-quotes, that it would look strange.

Personally I don't think it would look that strange, but maybe
that's just me. Does anyone else want to weigh in here?

I think the big question is whether single quotes appear in function
bodies so often that we should suggest folks just use $$ all the
time.

IME, the answer to that question is yes.

Cheers,
D
--
David Fetter david@fetter.org http://fetter.org/
phone: +1 510 893 6100 mobile: +1 415 235 3778

Remember to vote!

Neil Conway <neilc@samurai.com> writes:

On 6-May-04, at 12:41 AM, Bruce Momjian wrote:

OK. I am just afraid if we show 4 functions, and three use $$, and one
doesn't use single-quotes inside, so we quote with single-quotes, that
it would look strange.

Personally I don't think it would look that strange, but maybe that's
just me. Does anyone else want to weigh in here?

I think we *have to* show examples both ways, otherwise people will get
the impression that they *must* use $$ quotes and that all their
existing function definitions are broken.

I don't mind if the bulk of the examples are converted to whatever
seems clearest, but certainly the CREATE FUNCTION reference page
has to show both alternatives.

regards, tom lane

Tom Lane wrote:

Neil Conway <neilc@samurai.com> writes:

On 6-May-04, at 12:41 AM, Bruce Momjian wrote:

OK. I am just afraid if we show 4 functions, and three use $$, and one
doesn't use single-quotes inside, so we quote with single-quotes, that
it would look strange.

Personally I don't think it would look that strange, but maybe that's
just me. Does anyone else want to weigh in here?

I think we *have to* show examples both ways, otherwise people will get
the impression that they *must* use $$ quotes and that all their
existing function definitions are broken.

I don't mind if the bulk of the examples are converted to whatever
seems clearest, but certainly the CREATE FUNCTION reference page
has to show both alternatives.

Agreed we have to show both. The question is whether we should prefer
single quotes and switch to $$ only when a single quote exists in the
body, or use $$ in most cases. Of course CREATE FUNCTION should show
that both are possible, as well as $tag$.

-- 
  Bruce Momjian                        |  http://candle.pha.pa.us
  pgman@candle.pha.pa.us               |  (610) 359-1001
  +  If your life is a hard drive,     |  13 Roberts Road
  +  Christ can be your backup.        |  Newtown Square, Pennsylvania 19073

Bruce Momjian wrote:

Agreed we have to show both. The question is whether we should prefer
single quotes and switch to $$ only when a single quote exists in the
body, or use $$ in most cases. Of course CREATE FUNCTION should show
that both are possible, as well as $tag$.

My take: If there are no single quotes inside, use '. If there are
single quotes inside, use $$. If there is $$ inside, use $x$ (or some
other short sequence, not the function name). This conveys the
decision process we made when we designed this feature. If there are
several related examples in one section, use the same method for all.