Thread: Dollar Quoting doc patch--resend.
Neil, Here it is :) Cheers, D -- David Fetter david@fetter.org http://fetter.org/ phone: +1 510 893 6100 mobile: +1 415 235 3778 Remember to vote!
Attachment
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>. 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: >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>. > >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
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
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.