First draft at doc for file-enable-sql-reader-syntax

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

diff --git a/doc/ref-connect.xml b/doc/ref-connect.xml
index 84b33e519faaeb34355a07f122fcf3913d70908e..a30aaf13e0a78e69c7765499a27087fbbfc5d267 100644 (file)
--- a/doc/ref-connect.xml
+++ b/doc/ref-connect.xml
@@ -22,7 +22,7 @@
         <refentrytitle>DATABASE</refentrytitle>
       </refmeta>
     <refnamediv>
-      <refname><emphasis>Class</emphasis> <emphasis role="bold">DATABASE</emphasis></refname>
+      <refname>DATABASE</refname>
       <refpurpose>The super-type of all &clsql; databases</refpurpose>
       <refclass>Class</refclass>
     </refnamediv>
@@ -71,7 +71,7 @@
       <refentrytitle>*CONNECT-IF-EXISTS*</refentrytitle>
     </refmeta>
     <refnamediv>
-      <refname><emphasis>Variable</emphasis> <emphasis role="bold">*CONNECT-IF-EXISTS*</emphasis></refname>
+      <refname>*CONNECT-IF-EXISTS*</refname>
       <refpurpose>Default value for the
       <parameter>if-exists</parameter> parameter of <link
       linkend="connect"><function>connect</function></link>.</refpurpose>
@@ -80,7 +80,7 @@
     <refsect1>
       <title>Value Type</title>
       <para>A valid argument to the <parameter>if-exists</parameter> 
-      parameter of <function>connect</function>, i.e. one of
+      parameter of <function>connect</function>, that is, one of
       <simplelist type="inline">
         <member><symbol>:new</symbol></member>
         <member><symbol>:warn-new</symbol></member>
@@ -131,7 +131,7 @@
       <refentrytitle>*DEFAULT-DATABASE*</refentrytitle>
     </refmeta>
     <refnamediv>
-      <refname><emphasis>Variable</emphasis> <emphasis role="bold">*DEFAULT-DATABASE*</emphasis></refname>
+      <refname>*DEFAULT-DATABASE*</refname>
       <refpurpose>The default database object to use.</refpurpose>
       <refclass>Variable</refclass>
     </refnamediv>
@@ -241,7 +241,7 @@
       <refentrytitle>*DEFAULT-DATABASE-TYPE*</refentrytitle>
     </refmeta>
     <refnamediv>
-      <refname><emphasis>Variable</emphasis> <emphasis role="bold">*DEFAULT-DATABASE-TYPE*</emphasis></refname>
+      <refname>*DEFAULT-DATABASE-TYPE*</refname>
       <refpurpose>The default database type to use</refpurpose>
       <refclass>Variable</refclass>
     </refnamediv>
@@ -300,7 +300,7 @@
       <refentrytitle>*INITIALIZED-DATABASE-TYPES*</refentrytitle>
     </refmeta>
     <refnamediv>
-      <refname><emphasis>Variable</emphasis> <emphasis role="bold">*INITIALIZED-DATABASE-TYPES*</emphasis></refname>
+      <refname>*INITIALIZED-DATABASE-TYPES*</refname>
       <refpurpose>List of all initialized database types</refpurpose>
       <refclass>Variable</refclass>
     </refnamediv>
@@ -365,14 +365,13 @@
       <refentrytitle>CONNECT</refentrytitle>
     </refmeta>
     <refnamediv>
-      <refname><emphasis>Function</emphasis> <emphasis role="bold">CONNECT</emphasis></refname>
+      <refname>CONNECT</refname>
       <refpurpose>create a connection to a database.</refpurpose>
       <refclass>Function</refclass>
     </refnamediv>
     <refsect1>
       <title>Syntax</title>
-       <title>Syntax</title>
-       <synopsis><function>connect</function> <replaceable>connection-spec</replaceable> &amp;key <replaceable>if-exists</replaceable> <replaceable>database-type</replaceable> <replaceable>pool</replaceable> <replaceable>make-default</replaceable> => <returnvalue>database</returnvalue></synopsis>
+      <synopsis><function>connect</function> <replaceable>connection-spec</replaceable> &amp;key <replaceable>if-exists</replaceable> <replaceable>database-type</replaceable> <replaceable>pool</replaceable> <replaceable>make-default</replaceable> => <returnvalue>database</returnvalue></synopsis>
     </refsect1>
     <refsect1>
       <title>Arguments and Values</title>
@@ -380,8 +379,14 @@
         <varlistentry>
           <term><parameter>connection-spec</parameter></term>
           <listitem>
-            <para>A vendor specific connection specification supplied
-            as a list or as a string.</para>
+            <para>A SQL backend specific connection specification
+            supplied as a list or as a string.</para>
+            <para>For the MySQL backend, this list includes an
+            optional associative list of connection options. The
+            options list is parsed and supplied to the MySQL API
+            using <function>mysql_options</function> in between the
+            calls to <function>mysql_init</function>
+            and <function>mysql_real_connect</function>.</para>
           </listitem>
         </varlistentry>
         <varlistentry>
@@ -589,7 +594,7 @@
       <refentrytitle>CONNECTED-DATABASES</refentrytitle>
     </refmeta>
     <refnamediv>
-      <refname><emphasis>Function</emphasis> <emphasis role="bold">CONNECTED-DATABASES</emphasis></refname>
+      <refname>CONNECTED-DATABASES</refname>
       <refpurpose>Return the list of active database objects.</refpurpose>
       <refclass>Function</refclass>
     </refnamediv>
@@ -681,7 +686,7 @@
       <refentrytitle>DATABASE-NAME</refentrytitle>
     </refmeta>
     <refnamediv>
-      <refname><emphasis>Generic Function</emphasis> <emphasis role="bold">DATABASE-NAME</emphasis></refname>
+      <refname>DATABASE-NAME</refname>
       <refpurpose>Get the name of a database object</refpurpose>
       <refclass>Generic Function</refclass>
     </refnamediv>
@@ -798,7 +803,7 @@
         <refentrytitle>DATABASE-NAME-FROM-SPEC</refentrytitle>
       </refmeta>
       <refnamediv>
-       <refname><emphasis>Generic Function</emphasis> <emphasis role="bold">DATABASE-NAME-FROM-SPEC</emphasis></refname>
+       <refname>DATABASE-NAME-FROM-SPEC</refname>
        <refpurpose>Return the database name string corresponding to
          the given connection specification.</refpurpose>
        <refclass>Generic Function</refclass>
@@ -911,7 +916,7 @@
       <refentrytitle>DATABASE-TYPE</refentrytitle>
     </refmeta>
     <refnamediv>
-      <refname><emphasis>Generic Function</emphasis> <emphasis role="bold">DATABASE-TYPE</emphasis></refname>
+      <refname>DATABASE-TYPE</refname>
       <refpurpose>Get the type of a database object.</refpurpose>
       <refclass>Generic Function</refclass>
     </refnamediv>
@@ -1000,7 +1005,7 @@
       <refentrytitle>DISCONNECT</refentrytitle>
     </refmeta>
     <refnamediv>
-      <refname><emphasis>Function</emphasis> <emphasis role="bold">DISCONNECT</emphasis></refname>
+      <refname>DISCONNECT</refname>
        <refpurpose>close a database connection</refpurpose>
        <refclass>Function</refclass>
       </refnamediv>
@@ -1115,7 +1120,7 @@
         <refentrytitle>DISCONNECT-POOLED</refentrytitle>
       </refmeta>
       <refnamediv>
-        <refname><emphasis>Function</emphasis> <emphasis role="bold">DISCONNECT-POOLED</emphasis></refname>
+        <refname>DISCONNECT-POOLED</refname>
         <refpurpose>closes all pooled database connections</refpurpose>
         <refclass>Function</refclass>
       </refnamediv>
@@ -1179,7 +1184,7 @@
       <refentrytitle>FIND-DATABASE</refentrytitle>
     </refmeta>
     <refnamediv>
-      <refname><emphasis>Function</emphasis> <emphasis role="bold">FIND-DATABASE</emphasis></refname>
+      <refname>FIND-DATABASE</refname>
       <refpurpose>>Locate a database object through it's
       name.</refpurpose>
       <refclass>Function</refclass>
@@ -1331,7 +1336,7 @@
       <refentrytitle>INITIALIZE-DATABASE-TYPE</refentrytitle>
     </refmeta>
     <refnamediv>
-      <refname><emphasis>Function</emphasis> <emphasis role="bold">INITIALIZE-DATABASE-TYPE</emphasis></refname>
+      <refname>INITIALIZE-DATABASE-TYPE</refname>
       <refpurpose>Initializes a database type</refpurpose>
       <refclass>Function</refclass>
     </refnamediv>
@@ -1445,7 +1450,7 @@
       <refentrytitle>RECONNECT</refentrytitle>
     </refmeta>
     <refnamediv>
-      <refname><emphasis>Function</emphasis> <emphasis role="bold">RECONNECT</emphasis></refname>
+      <refname>RECONNECT</refname>
       <refpurpose>Re-establishes the connection between a database object and its RDBMS.</refpurpose>
       <refclass>Function</refclass>
     </refnamediv>
@@ -1570,7 +1575,7 @@
       <refentrytitle>STATUS</refentrytitle>
     </refmeta>
     <refnamediv>
-      <refname><emphasis>Function</emphasis> <emphasis role="bold">STATUS</emphasis></refname>
+      <refname>STATUS</refname>
       <refpurpose>Print information about connected databases.</refpurpose>
       <refclass>Function</refclass>
     </refnamediv>
@@ -1677,7 +1682,7 @@ CLSQL STATUS: 2004-06-13 15:08:08
       <refentrytitle>CREATE-DATABASE</refentrytitle>
     </refmeta>
     <refnamediv>
-      <refname><emphasis>Function</emphasis> <emphasis role="bold">CREATE-DATABASE</emphasis></refname>
+      <refname>CREATE-DATABASE</refname>
        <refpurpose>create a database</refpurpose>
        <refclass>Function</refclass>
       </refnamediv>
@@ -1775,7 +1780,7 @@ error: 'Access denied for user: 'root@localhost' (Using password: YES)'
       <refentrytitle>DESTROY-DATABASE</refentrytitle>
     </refmeta>
     <refnamediv>
-      <refname><emphasis>Function</emphasis> <emphasis role="bold">DESTROY-DATABASE</emphasis></refname>
+      <refname>DESTROY-DATABASE</refname>
        <refpurpose>destroys a database</refpurpose>
        <refclass>Function</refclass>
       </refnamediv>
@@ -1826,7 +1831,7 @@ error: 'Access denied for user: 'root@localhost' (Using password: YES)'
 =>
 Error: While trying to access database localhost/test2/root
   using database-type POSTGRESQL:
-  Error database-destory failed: dropdb: database removal failed: ERROR:  database "test2" does not exist
+  Error database-destroy failed: dropdb: database removal failed: ERROR:  database "test2" does not exist
   has occurred.
   [condition type: CLSQL-ACCESS-ERROR]
        </screen>
@@ -1872,7 +1877,7 @@ Error: While trying to access database localhost/test2/root
       <refentrytitle>PROBE-DATABASE</refentrytitle>
     </refmeta>
     <refnamediv>
-      <refname><emphasis>Function</emphasis> <emphasis role="bold">PROBE-DATABASE</emphasis></refname>
+      <refname>PROBE-DATABASE</refname>
        <refpurpose>tests for existence of a database</refpurpose>
        <refclass>Function</refclass>
       </refnamediv>
@@ -1955,7 +1960,7 @@ Error: While trying to access database localhost/test2/root
       <refentrytitle>LIST-DATABASES</refentrytitle>
     </refmeta>
     <refnamediv>
-      <refname><emphasis>Function</emphasis> <emphasis role="bold">LIST-DATABASES</emphasis></refname>
+      <refname>LIST-DATABASES</refname>
       <refpurpose>List databases matching the supplied connection spec
       and database type.</refpurpose>
       <refclass>Function</refclass>
@@ -2053,7 +2058,7 @@ Error: While trying to access database localhost/test2/root
       <refentrytitle>WITH-DATABASE</refentrytitle>
     </refmeta>
     <refnamediv>
-      <refname><emphasis>Macro</emphasis> <emphasis role="bold">WITH-DATABASE</emphasis></refname>
+      <refname>WITH-DATABASE</refname>
       <refpurpose>Execute a body of code with a variable bound to a
       specified database object.</refpurpose>
       <refclass>Macro</refclass>
@@ -2069,7 +2074,7 @@ Error: While trying to access database localhost/test2/root
         <varlistentry>
           <term><parameter>db-var</parameter></term>
           <listitem>
-            <para>A variable to which the specified database is bound. 
+            <para>A variable which is bound to the specified database.
             </para>
           </listitem>
         </varlistentry>
@@ -2083,7 +2088,12 @@ Error: While trying to access database localhost/test2/root
         <varlistentry>
           <term><parameter>connect-args</parameter></term>
           <listitem>
-            <para>Other optional arguments to <function>connect</function>. 
+            <para>Other optional arguments to
+            <function>connect</function>. This macro use a value of
+            &nil; for <function>connect</function>'s
+            <replaceable>make-default</replaceable> key, This is in
+            contrast to to the connect function which has a default
+            value of &t; for <replaceable>make-default</replaceable>.
             </para>
           </listitem>
         </varlistentry>
@@ -2169,7 +2179,7 @@ Error: While trying to access database localhost/test2/root
       <refentrytitle>WITH-DEFAULT-DATABASE</refentrytitle>
     </refmeta>
     <refnamediv>
-      <refname><emphasis>Macro</emphasis> <emphasis role="bold">WITH-DEFAULT-DATABASE</emphasis></refname>
+      <refname>WITH-DEFAULT-DATABASE</refname>
       <refpurpose>Execute a body of code with <symbol>*default-database*</symbol> bound to a specified database.</refpurpose>
       <refclass>Macro</refclass>
     </refnamediv>