r9734: Document idiosyncrasies of the individual backends and differences from CommonSQL.

[clsql.git] / doc / ref-syntax.xml

diff --git a/doc/ref-syntax.xml b/doc/ref-syntax.xml
index b13dd32ff0cd7c279673e28e464efe1592244ffe..c83cab344d41ad08852dfb922f4db23adba092a7 100644 (file)
--- a/doc/ref-syntax.xml
+++ b/doc/ref-syntax.xml
@@ -84,6 +84,11 @@
       <para>
         The symbolic SQL syntax is disabled by default. 
       </para>
+      <para> 
+        &clsql; differs from &commonsql; in that
+        <function>enable-sql-reader-syntax</function> is defined as a
+        macro rather than a function.
+      </para>
     </refsect1>
   </refentry>
 
@@ -153,6 +158,11 @@
       <para>
         The symbolic SQL syntax is disabled by default. 
       </para>
+      <para> 
+        &clsql; differs from &commonsql; in that
+        <function>disable-sql-reader-syntax</function> is defined as a
+        macro rather than a function.
+      </para>
     </refsect1>
   </refentry>
 
@@ -225,6 +235,11 @@
       <para>
         The symbolic SQL syntax is disabled by default. 
       </para>
+      <para> 
+        &clsql; differs from &commonsql; in that
+        <function>locally-enable-sql-reader-syntax</function> is
+        defined as a macro rather than a function.
+      </para>
     </refsect1>
   </refentry>
 
@@ -302,6 +317,11 @@
       <para>
         The symbolic SQL syntax is disabled by default. 
       </para>
+      <para> 
+        &clsql; differs from &commonsql; in that
+        <function>locally-disable-sql-reader-syntax</function> is
+        defined as a macro rather than a function.
+      </para>
     </refsect1>
   </refentry>
 
@@ -381,6 +401,11 @@
       <para>
         The symbolic SQL syntax is disabled by default. 
       </para>
+      <para> 
+        &clsql; differs from &commonsql; in that
+        <function>restore-sql-reader-syntax-state</function> is
+        defined as a macro rather than a function.
+      </para>
     </refsect1>
   </refentry>
 
@@ -653,7 +678,7 @@
     <refsect1>
       <title>Syntax</title>
       <synopsis>
-      <function>sql-operation</function> <parameter>operation</parameter> <function>&amp;rest</function> <parameter>args</parameter> => <returnvalue>result</returnvalue></synopsis>
+      <function>sql-operation</function> <parameter>operator</parameter> <function>&amp;rest</function> <parameter>args</parameter> => <returnvalue>result</returnvalue></synopsis>
       <synopsis>
       <function>sql-operation</function> 'function <parameter>func</parameter> <function>&amp;rest</function> <parameter>args</parameter> => <returnvalue>result</returnvalue></synopsis>
     </refsect1>
@@ -661,7 +686,7 @@
       <title>Arguments and Values</title>
       <variablelist>
         <varlistentry>
-          <term><parameter>operation</parameter></term>
+          <term><parameter>operator</parameter></term>
           <listitem>
             <para>A symbol denoting an SQL operator.</para>
           </listitem>
@@ -689,9 +714,9 @@
     <refsect1>
       <title>Description</title>
       <para>Returns an SQL expression constructed from the supplied
-      SQL operator or function <parameter>operation</parameter> and
+      SQL operator or function <parameter>operator</parameter> and
       its arguments <parameter>args</parameter>. If
-      <parameter>operation</parameter> is passed the symbol 'function
+      <parameter>operator</parameter> is passed the symbol 'function
       then the first value in <parameter>args</parameter> is taken to
       be a valid SQL function and the remaining values in
       <parameter>args</parameter> its arguments.
@@ -728,7 +753,7 @@
       <title>Exceptional Situations</title>
       <para>An error of type <link
       linkend="sql-user-error"><function>sql-user-error</function></link>
-      is signalled if <parameter>operation</parameter> is not a symbol
+      is signalled if <parameter>operator</parameter> is not a symbol
       representing a supported SQL operator.</para>
     </refsect1>
     <refsect1>
@@ -757,13 +782,13 @@
     <refsect1>
       <title>Syntax</title>
       <synopsis>
-      <function>sql-operator</function> <parameter>operation</parameter> => <returnvalue>result</returnvalue></synopsis>
+      <function>sql-operator</function> <parameter>operator</parameter> => <returnvalue>result</returnvalue></synopsis>
     </refsect1>
     <refsect1>
       <title>Arguments and Values</title>
       <variablelist>
         <varlistentry>
-          <term><parameter>operation</parameter></term>
+          <term><parameter>operator</parameter></term>
           <listitem>
             <para>A symbol denoting an SQL operator.</para>
           </listitem>
@@ -779,9 +804,9 @@
     </refsect1>
     <refsect1>
       <title>Description</title>
-      <para>Returns the Lisp symbol corresponding to the SQL operation
-      represented by the symbol <parameter>operation</parameter>. If 
-      <parameter>operation</parameter> does not represent a supported 
+      <para>Returns the Lisp symbol corresponding to the SQL operator
+      represented by the symbol <parameter>operator</parameter>. If 
+      <parameter>operator</parameter> does not represent a supported 
       SQL operator or is not a symbol, nil is returned. 
       </para>
     </refsect1>
@@ -816,8 +841,9 @@
     </refsect1>
     <refsect1>
       <title>Notes</title>
-      <para>&clsql;'s symbolic SQL syntax currently has support for
-      the following SQL operators:
+      <para>
+        &clsql;'s symbolic SQL syntax currently has support for the
+        following &commonsql; compatible SQL operators:
       </para> 
       <simplelist> 
         <!-- CommonSQL Compatible --> 
@@ -894,8 +920,15 @@
         <member><function>slot-value
         </function></member>, 
         <member><function>userenv 
-        <!-- CLSQL Extensions --> 
         </function></member>, 
+      </simplelist> 
+      <para>
+        as well as the pseudo-operator <function>function</function>. 
+      </para>
+      <para> The following operators are provided as &clsql; extensions to 
+      the &commonsql; API. 
+      <simplelist> 
+        <!-- CLSQL Extensions --> 
         <member><function>concat
         </function></member>, 
         <member><function>substring 
@@ -920,13 +953,15 @@
         </function></member>, 
         <member><function>coalesce 
         </function></member>, 
-        <member><function>view-class
+        <member><function>view-class.
         </function></member> 
-      </simplelist> 
-      <para>as well as the pseudo-operator
-      <function>function</function>. Note that some of these operators
-      are not supported by all of the RDBMS supported by
-      &clsql;.</para>
+      </simplelist>
+      </para>
+      <para> 
+        Note that some of these operators are not supported by all of
+        the RDBMS supported by &clsql; (see the <link
+        linkend="appendix">Appendix</link> for details).
+      </para>
     </refsect1>
   </refentry>