Some editorializing on the docs for the dollar-quoting feature: fix

grammar, don't drop discussions into the middle of unrelated discussions,
etc.

doc/src/sgml/datatype.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.149 2004/09/20 04:19:50 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.150 2004/09/20 22:48:25 tgl Exp $
 -->
 
  <chapter id="datatype">
@@ -507,6 +507,16 @@ NUMERIC
      declared limits, an error is raised.
     </para>
 
+    <para>
+     In addition to ordinary numeric values, the <type>numeric</type>
+     type allows the special value <literal>NaN</>, meaning 
+     <quote>not-a-number</quote>.  Any operation on <literal>NaN</>
+     yields another <literal>NaN</>.  When writing this value
+     as a constant in a SQL command, you must put quotes around it,
+     for example <literal>UPDATE table SET x = 'NaN'</>.  On input,
+     the string <literal>NaN</> is recognized in a case-insensitive manner.
+    </para>
+
     <para>
      The types <type>decimal</type> and <type>numeric</type> are
      equivalent.  Both types are part of the <acronym>SQL</acronym>
@@ -595,6 +605,24 @@ NUMERIC
      from zero will cause an underflow error.
     </para>
 
+    <para>
+     In addition to ordinary numeric values, the floating-point types
+     have several special values:
+<literallayout>
+<literal>Infinity</literal>
+<literal>-Infinity</literal>
+<literal>NaN</literal>
+</literallayout>
+     These represent the IEEE 754 special values
+     <quote>infinity</quote>, <quote>negative infinity</quote>, and
+     <quote>not-a-number</quote>, respectively.  (On a machine whose
+     floating-point arithmetic does not follow IEEE 754, these values
+     will probably not work as expected.)  When writing these values
+     as constants in a SQL command, you must put quotes around them,
+     for example <literal>UPDATE table SET x = 'Infinity'</>.  On input,
+     these strings are recognized in a case-insensitive manner.
+    </para>
+
     <para>
      <productname>PostgreSQL</productname> also supports the SQL-standard
      notations <type>float</type> and

doc/src/sgml/plperl.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/plperl.sgml,v 2.27 2004/08/18 03:37:56 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/plperl.sgml,v 2.28 2004/09/20 22:48:25 tgl Exp $
 -->
 
  <chapter id="plperl">
@@ -47,17 +47,22 @@ $PostgreSQL: pgsql/doc/src/sgml/plperl.sgml,v 2.27 2004/08/18 03:37:56 momjian E
   <para>
    To create a function in the PL/Perl language, use the standard syntax:
 <programlisting>
-CREATE FUNCTION <replaceable>funcname</replaceable>
+CREATE FUNCTION <replaceable>funcname</replaceable> (<replaceable>argument-types</replaceable>) RETURNS <replaceable>return-type</replaceable> AS $$
-(<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. Since the body of
+   The body of the function is ordinary Perl code.
-   the function is treated as a string by
+  </para>
-   <productname>PostgreSQL</productname>, it can be specified using
+
-   dollar quoting (as shown above), or via the legacy single quote
+   <para>
-   syntax (see <xref linkend="sql-syntax-strings"> for more
+    The syntax of the <command>CREATE FUNCTION</command> command requires
-   information).
+    the function body to be written as a string constant.  It is usually
+    most convenient to use dollar quoting (see <xref
+    linkend="sql-syntax-dollar-quoting">) for the string constant.
+    If you choose to use regular single-quoted string constant syntax,
+    you must escape single quote marks (<literal>'</>) and backslashes
+    (<literal>\</>) used in the body of the function, typically by
+    doubling them (see <xref linkend="sql-syntax-strings">).
    </para>
 
   <para>

doc/src/sgml/pltcl.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/pltcl.sgml,v 2.30 2004/05/16 23:22:07 neilc Exp $
+$PostgreSQL: pgsql/doc/src/sgml/pltcl.sgml,v 2.31 2004/09/20 22:48:25 tgl Exp $
 -->
 
  <chapter id="pltcl">
@@ -400,7 +400,7 @@ $$ LANGUAGE pltcl;
       <term><function>quote</> <replaceable>string</replaceable></term>
       <listitem>
        <para>
-	Duplicates all occurrences of single quote and backslash characters
+	Doubles all occurrences of single quote and backslash characters
 	in the given string.  This may be used to safely quote strings
 	that are to be inserted into SQL commands given
 	to <function>spi_exec</function> or
@@ -422,10 +422,10 @@ SELECT 'doesn't' AS ret
 	which would cause a parse error during
 	<function>spi_exec</function> or
 	<function>spi_prepare</function>.
-	The submitted command should contain
+	To work properly, the submitted command should contain
 
 <programlisting>
-SELECT $q$doesn't$q$ AS ret
+SELECT 'doesn''t' AS ret
 </programlisting>
 
 	which can be formed in PL/Tcl using

doc/src/sgml/ref/create_function.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.60 2004/09/16 04:16:08 neilc Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.61 2004/09/20 22:48:29 tgl Exp $
 -->
 
 <refentry id="SQL-CREATEFUNCTION">
@@ -264,16 +264,9 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
 
      <listitem>
       <para>
-       A string defining the function; the meaning depends on the
+       A string constant defining the function; the meaning depends on the
        language.  It may be an internal function name, the path to an
-       object file, an SQL command, or text in a procedural
+       object file, an SQL command, or text in a procedural language.
-       language. When this string contains the text of a procedural
-       language function definition, it may be helpful to use dollar
-       quoting to specify this string, rather than the normal single
-       quote syntax (this avoids the need to escape any single quotes
-       that occur in the function definition itself). For more
-       information on dollar quoting, see <xref
-       linkend="sql-syntax-strings">.
       </para>
      </listitem>
     </varlistentry>
@@ -379,8 +372,11 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
    </para>
 
    <para>
-   Unless dollar quoting is used, any single quotes or backslashes in
+    It is often helpful to use dollar quoting (see <xref
-   the function definition must be escaped by doubling them.
+    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>

doc/src/sgml/syntax.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/syntax.sgml,v 1.94 2004/06/16 01:26:38 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/syntax.sgml,v 1.95 2004/09/20 22:48:25 tgl Exp $
 -->
 
 <chapter id="sql-syntax">
@@ -223,8 +223,8 @@ UPDATE "my_table" SET "a" = 5;
     strings, bit strings, and numbers.
     Constants can also be specified with explicit types, which can
     enable more accurate representation and more efficient handling by
-    the system. The implicit constants are described below; explicit
+    the system. These alternatives are discussed in the following
-    constants are discussed afterwards.
+    subsections.
    </para>
 
    <sect3 id="sql-syntax-strings">
@@ -240,76 +240,21 @@ UPDATE "my_table" SET "a" = 5;
       <primary>quotation marks</primary>
       <secondary>escaping</secondary>
      </indexterm>
-     <indexterm>
+     A string constant in SQL is an arbitrary sequence of characters
-      <primary>dollar quoting</primary>
+     bounded by single quotes (<literal>'</literal>), for example
-     </indexterm>
+     <literal>'This is a string'</literal>.  The standard-compliant way of
-      <productname>PostgreSQL</productname> provides two ways to
+     writing a single-quote character within a string constant is to
-      specify a string constant. The first way is to enclose the
+     write two adjacent single quotes, e.g.
-      sequence of characters that constitute the string in single
+     <literal>'Dianne''s horse'</literal>.
-      quotes (<literal>'</literal>), e.g. <literal>'This is a
+     <productname>PostgreSQL</productname> also allows single quotes
-      string'</literal>. This method of specifying a string constant
+     to be escaped with a backslash (<literal>\</literal>), so for
-      is defined by the SQL standard. The standard-compliant way of
+     example the same string could be written
-      embedding single-quotes these kinds of string constants is by
+     <literal>'Dianne\'s horse'</literal>.
-      typing two adjacent single quotes, e.g. <literal>'Dianne''s
-      house'</literal>. In addition,
-      <productname>PostgreSQL</productname> allows single quotes
-      to be escaped with a backslash (<literal>\</literal>),
-      e.g. <literal>'Dianne\'s horse'</literal>.
     </para>
 
     <para>
-      While this syntax for specifying string constants is usually
+     Another <productname>PostgreSQL</productname> extension is that
-      convenient, it can be difficult to comprehend the content of the
+     C-style backslash escapes are available:
-      string if it consists of many single quotes, each of which must
-      be doubled. To allows more readable queries in these situations,
-      <productname>PostgreSQL</productname> allows another way to
-      specify string constants known as <quote>dollar
-      quoting</quote>. A string constant specified via dollar quoting
-      consists of a dollar sign (<literal>$</literal>), an optional
-      <quote>tag</quote> of zero or more characters, another dollar
-      sign, an arbitrary sequence of characters that makes up the
-      string content, a dollar sign, the same tag that began this
-      dollar quote, and a dollar sign. For example, here are two
-      different ways to specify the previous example using dollar
-      quoting:
-<programlisting>
-$$Dianne's horse$$
-$SomeTag$Dianne's horse$SomeTag$
-</programlisting>
-      Note that inside the dollar-quoted string, single quotes can be
-      used without needing to be escaped.
-     </para>
-
-     <para>
-      Dollar quotes are case sensitive, so <literal>$tag$String
-      content$tag$</literal> is valid, but <literal>$TAG$String
-      content$tag$</literal> is not.  Also, dollar quotes can
-      nest. For example:
-<programlisting>
-CREATE OR REPLACE FUNCTION has_bad_chars(text) RETURNS boolean AS
-$function$
-BEGIN
-    RETURN ($1 ~ $q$[\t\r\n\v|\\]$q$);
-END;
-$function$ LANGUAGE plpgsql;
-</programlisting>
-      Note that nesting requires a different tag for each nested
-      dollar quote, as shown above. Furthermore, nested dollar quotes
-      can only be used when the content of the string that is being
-      quoted will be re-parsed by <productname>PostgreSQL</>.
-     </para>
-
-     <para>
-      Dollar quoting is not defined by the SQL standard, but it is
-      often a more convenient way to write long string literals (such
-      as procedural function definitions) than the standard-compliant
-      single quote syntax. Which quoting technique is most appropriate
-      for a particular circumstance is a decision that is left to the
-      user.
-     </para>
-
-    <para>
-     C-style backslash escapes are also available:
      <literal>\b</literal> is a backspace, <literal>\f</literal> is a
      form feed, <literal>\n</literal> is a newline,
      <literal>\r</literal> is a carriage return, <literal>\t</literal>
@@ -319,7 +264,7 @@ $function$ LANGUAGE plpgsql;
      that the byte sequences you create are valid characters in the
      server character set encoding.)  Any other character following a
      backslash is taken literally.  Thus, to include a backslash in a
-     string constant, type two backslashes.
+     string constant, write two backslashes.
     </para>
 
     <para>
@@ -349,6 +294,86 @@ SELECT 'foo'      'bar';
     </para>
    </sect3>
 
+   <sect3 id="sql-syntax-dollar-quoting">
+    <title>Dollar-Quoted String Constants</title>
+
+     <indexterm>
+      <primary>dollar quoting</primary>
+     </indexterm>
+
+    <para>
+     While the standard syntax for specifying string constants is usually
+     convenient, it can be difficult to understand when the desired string
+     contains many single quotes or backslashes, since each of those must
+     be doubled. To allow more readable queries in such situations,
+     <productname>PostgreSQL</productname> provides another way, called
+     <quote>dollar quoting</quote>, to write string constants.
+     A dollar-quoted string constant
+     consists of a dollar sign (<literal>$</literal>), an optional
+     <quote>tag</quote> of zero or more characters, another dollar
+     sign, an arbitrary sequence of characters that makes up the
+     string content, a dollar sign, the same tag that began this
+     dollar quote, and a dollar sign. For example, here are two
+     different ways to specify the string <quote>Dianne's horse</>
+     using dollar quoting:
+<programlisting>
+$$Dianne's horse$$
+$SomeTag$Dianne's horse$SomeTag$
+</programlisting>
+     Notice that inside the dollar-quoted string, single quotes can be
+     used without needing to be escaped.  Indeed, no characters inside
+     a dollar-quoted string are ever escaped: the string content is always
+     written literally.  Backslashes are not special, and neither are
+     dollar signs, unless they are part of a sequence matching the opening
+     tag.
+    </para>
+
+    <para>
+     It is possible to nest dollar-quoted string constants by choosing
+     different tags at each nesting level.  This is most commonly used in
+     writing function definitions.  For example:
+<programlisting>
+$function$
+BEGIN
+    RETURN ($1 ~ $q$[\t\r\n\v\\]$q$);
+END;
+$function$
+</programlisting>
+     Here, the sequence <literal>$q$[\t\r\n\v\\]$q$</> represents a
+     dollar-quoted literal string <literal>[\t\r\n\v\\]</>, which will
+     be recognized when the function body is executed by
+     <productname>PostgreSQL</>.  But since the sequence does not match
+     the outer dollar quoting delimiter <literal>$function$</>, it is
+     just some more characters within the constant so far as the outer
+     string is concerned.
+    </para>
+
+    <para>
+     The tag, if any, of a dollar-quoted string follows the same rules
+     as an unquoted identifier, except that it cannot contain a dollar sign.
+     Tags are case sensitive, so <literal>$tag$String content$tag$</literal>
+     is correct, but <literal>$TAG$String content$tag$</literal> is not.
+    </para>
+
+    <para>
+     A dollar-quoted string that follows a keyword or identifier must
+     be separated from it by whitespace; otherwise the dollar quoting
+     delimiter would be taken as part of the preceding identifier.
+    </para>
+
+    <para>
+     Dollar quoting is not part of the SQL standard, but it is often a more
+     convenient way to write complicated string literals than the
+     standard-compliant single quote syntax.  It is particularly useful when
+     representing string constants inside other constants, as is often needed
+     in procedural function definitions.  With single-quote syntax, each
+     backslash in the above example would have to be written as four
+     backslashes, which would be reduced to two backslashes in parsing the
+     original string constant, and then to one when the inner string constant
+     is re-parsed during function execution.
+    </para>
+   </sect3>
+
    <sect3 id="sql-syntax-bit-strings">
     <title>Bit-String Constants</title>
 
@@ -358,7 +383,7 @@ SELECT 'foo'      'bar';
     </indexterm>
 
     <para>
-     Bit-string constants look like string constants with a
+     Bit-string constants look like regular string constants with a
      <literal>B</literal> (upper or lower case) immediately before the
      opening quote (no intervening whitespace), e.g.,
      <literal>B'1001'</literal>.  The only characters allowed within
@@ -376,6 +401,7 @@ SELECT 'foo'      'bar';
     <para>
      Both forms of bit-string constant can be continued
      across lines in the same way as regular string constants.
+     Dollar quoting cannot be used in a bit-string constant.
     </para>
    </sect3>
 
@@ -417,23 +443,6 @@ SELECT 'foo'      'bar';
 </literallayout>
     </para>
 
-    <para>
-     In addition, there are several special constant values that are
-     accepted as numeric constants. The <type>float4</type> and
-     <type>float8</type> types allow the following special constants:
-<literallayout>
-Infinity
--Infinity
-NaN
-</literallayout>
-     These represent the IEEE 754 special values
-     <quote>infinity</quote>, <quote>negative infinity</quote>, and
-     <quote>not-a-number</quote>, respectively. The
-     <type>numeric</type> type only allows <literal>NaN</>, whereas
-     the integral types do not allow any of these constants. Note that
-     these constants are recognized in a case-insensitive manner.
-    </para>
-
     <para>
      <indexterm><primary>integer</primary></indexterm>
      <indexterm><primary>bigint</primary></indexterm>
@@ -462,6 +471,9 @@ NaN
 REAL '1.23'  -- string style
 1.23::REAL   -- PostgreSQL (historical) style
 </programlisting>
+
+     These are actually just special cases of the general casting
+     notations discussed next.
     </para>
    </sect3>
 
@@ -481,13 +493,17 @@ REAL '1.23'  -- string style
 '<replaceable>string</replaceable>'::<replaceable>type</replaceable>
 CAST ( '<replaceable>string</replaceable>' AS <replaceable>type</replaceable> )
 </synopsis>
-     The string's text is passed to the input conversion
+     The string constant's text is passed to the input conversion
      routine for the type called <replaceable>type</replaceable>. The
      result is a constant of the indicated type.  The explicit type
      cast may be omitted if there is no ambiguity as to the type the
-     constant must be (for example, when it is passed as an argument
+     constant must be (for example, when it is assigned directly to a
-     to a non-overloaded function), in which case it is automatically
+     table column), in which case it is automatically coerced.
-     coerced.
+    </para>
+
+    <para>
+     The string constant can be written using either regular SQL
+     notation or dollar-quoting.
     </para>
 
     <para>

doc/src/sgml/xfunc.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/xfunc.sgml,v 1.87 2004/09/13 20:05:25 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/xfunc.sgml,v 1.88 2004/09/20 22:48:25 tgl Exp $
 -->
 
  <sect1 id="xfunc">
@@ -103,21 +103,28 @@ $PostgreSQL: pgsql/doc/src/sgml/xfunc.sgml,v 1.87 2004/09/13 20:05:25 tgl Exp $
    </para>
 
    <para>
-    The body of an SQL function should be a list of one or more SQL
+    The body of an SQL function must be a list of SQL
-    statements separated by semicolons.  Although dollar quoting
+    statements separated by semicolons.  A semicolon after the last
-    obviates this, note that because the syntax of the <command>CREATE
+    statement is optional.  Unless the function is declared to return
-    FUNCTION</command> command, if you choose not to use dollar
+    <type>void</>, the last statement must be a <command>SELECT</>.
-    quoting, i.e. the body of the function is enclosed in single quotes,
-    you must escape single quote marks (<literal>'</>) used in the body of
-    the function, either by writing two single quotes (<literal>''</>) or
-    with a backslash (<literal>\'</>) where you desire each quote to be.
    </para>
 
    <para>
-    Arguments to the SQL function may be referenced in the function
+    The syntax of the <command>CREATE FUNCTION</command> command requires
-    body using the syntax <literal>$<replaceable>n</></>: <literal>$1</> refers to
+    the function body to be written as a string constant.  It is usually
-    the first argument, <literal>$2</> to the second, and so on.  If an argument
+    most convenient to use dollar quoting (see <xref
-    is of a composite type, then the dot notation,
+    linkend="sql-syntax-dollar-quoting">) for the string constant.
+    If you choose to use regular single-quoted string constant syntax,
+    you must escape single quote marks (<literal>'</>) and backslashes
+    (<literal>\</>) used in the body of the function, typically by
+    doubling them (see <xref linkend="sql-syntax-strings">).
+   </para>
+
+   <para>
+    Arguments to the SQL function are referenced in the function
+    body using the syntax <literal>$<replaceable>n</></>: <literal>$1</>
+    refers to the first argument, <literal>$2</> to the second, and so on.
+    If an argument is of a composite type, then the dot notation,
     e.g., <literal>$1.name</literal>, may be used to access attributes
     of the argument.
    </para>
@@ -664,7 +671,7 @@ DETAIL:  A function returning "anyarray" or "anyelement" must have at least one
     create an alias for the <function>sqrt</function> function:
 <programlisting>
 CREATE FUNCTION square_root(double precision) RETURNS double precision
-    AS $$dsqrt$$
+    AS 'dsqrt'
     LANGUAGE internal
     STRICT;
 </programlisting>