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

 <!--
-$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

 <!--
-$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,19 +47,24 @@ $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>
-(<replaceable>argument-types</replaceable>) RETURNS <replaceable>return-type</replaceable> AS $$
+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. Since the body of
-   the function is treated as a string by
-   <productname>PostgreSQL</productname>, it can be specified using
-   dollar quoting (as shown above), or via the legacy single quote
-   syntax (see <xref linkend="sql-syntax-strings"> for more
-   information).
+   The body of the function is ordinary Perl code.
   </para>
 
+   <para>
+    The syntax of the <command>CREATE FUNCTION</command> command requires
+    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>
    Arguments and results are handled as in any other Perl subroutine:
    Arguments are passed in <varname>@_</varname>, and a result value

doc/src/sgml/pltcl.sgml

 <!--
-$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

 <!--
-$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
-       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">.
+       object file, an SQL command, or text in a procedural language.
       </para>
      </listitem>
     </varlistentry>
@@ -378,10 +371,13 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
     functions.
    </para>
 
-  <para>
-   Unless dollar quoting is used, any single quotes or backslashes in
-   the function definition must be escaped by doubling them.
-  </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>
     To be able to define a function, the user must have the
@@ -410,9 +406,9 @@ CREATE FUNCTION add(integer, integer) RETURNS integer
 
 <programlisting>
 CREATE OR REPLACE FUNCTION increment(i integer) RETURNS integer AS '
-	BEGIN
-		RETURN i + 1;
-	END;' LANGUAGE plpgsql;
+        BEGIN
+                RETURN i + 1;
+        END;' LANGUAGE plpgsql;
 </programlisting>
   </para>
  </refsect1>

doc/src/sgml/xfunc.sgml

 <!--
-$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
-    statements separated by semicolons.  Although dollar quoting
-    obviates this, note that because the syntax of the <command>CREATE
-    FUNCTION</command> command, if you choose not to use dollar
-    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.
+    The body of an SQL function must be a list of SQL
+    statements separated by semicolons.  A semicolon after the last
+    statement is optional.  Unless the function is declared to return
+    <type>void</>, the last statement must be a <command>SELECT</>.
    </para>
 
    <para>
-    Arguments to the SQL function may be 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,
+    The syntax of the <command>CREATE FUNCTION</command> command requires
+    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>
+    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>