refactor test-connect and test-setup-database to be these two separate things (from...
[clsql.git] / doc / ref-connect.xml
index 4bc296b3fa843278fd26b9d80963f55a4dec18f5..1e299b949321ef412353e93ab91ed540090218c7 100644 (file)
@@ -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>
       <para>None.</para>
     </refsect1>
   </refentry>
+  <refentry id="db-pool-max-free-connections">
+    <refmeta>
+      <refentrytitle>*DB-POOL-MAX-FREE-CONNECTIONS*</refentrytitle>
+    </refmeta>
+    <refnamediv>
+      <refname>*DB-POOL-MAX-FREE-CONNECTIONS*</refname>
+      <refpurpose>How many free connections should the connection pool try to keep.</refpurpose>
+      <refclass>Parameter</refclass>
+    </refnamediv>
+    <refsect1>
+      <title>Value Type</title>
+      <para>Integer</para>
+    </refsect1>
+    <refsect1>
+      <title>Initial Value</title>
+      <para>4</para>
+    </refsect1>
+    <refsect1>
+      <title>Description</title>
+      <para>Threshold of free-connections in the pool before we
+  disconnect a database rather than returning it to the pool.  NIL for
+  no limit.  This is really a heuristic that should, on avg keep the
+  free connections about this size.</para>
+      <note>
+        <para>This is not a hard limit, the number of connections in
+        the pool may exceed this value.</para>
+      </note>
+    </refsect1>
+    <refsect1>
+      <title>Examples</title>
+      <screen>
+       (setf clsql-sys:*db-pool-max-free-connections* 2)
+      </screen>
+    </refsect1>
+    <refsect1>
+      <title>Affected By</title>
+      <para>None</para>
+    </refsect1>
+    <refsect1>
+      <title>See Also</title>
+      <para>
+        <simplelist>
+          <member><link linkend="connect"><function>connect</function></link></member>
+          <member><link linkend="disconnect"><function>disconnect</function></link></member>
+        </simplelist>
+      </para>
+    </refsect1>
+    <refsect1>
+      <title>Notes</title>
+      <note>
+       <para></para>
+      </note>
+    </refsect1>
+  </refentry>
+
 
   <refentry id="default-database">
     <refmeta>
       <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>
     <refsect1>
       <title>Value Type</title>
-      <para>Any object of type <type>database</type>, or nil to
+      <para>Any object of type <type>database</type>, or &nil; to
       indicate no default database.</para>
     </refsect1>
     <refsect1>
       <title>Initial Value</title>
-      <para><symbol>nil</symbol></para>
+      <para>&nil;</para>
     </refsect1>
     <refsect1>
       <title>Description</title>
       <symbol>*default-database*</symbol> to the first database
       that remains in the list of active databases as returned by
       <function>connected-databases</function>, or
-      <symbol>nil</symbol> if no further active databases
+      &nil; if no further active databases
       exist.</para>
       <para>The user may change <symbol>*default-database*</symbol>
       at any time to a valid value of his choice.</para>
       <caution>
         <para>If the value of <symbol>*default-database*</symbol> is
-        <symbol>nil</symbol>, then all calls to &clsql; functions on
+        &nil;, then all calls to &clsql; functions on
         databases must provide a suitable
         <parameter>database</parameter> parameter, or an error will be
         signalled.</para>
       <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>
     <refsect1>
       <title>Value Type</title>
       <para>Any keyword representing a valid database back-end of
-      &clsql;, or <symbol>nil</symbol>.</para>
+      &clsql;, or &nil;.</para>
     </refsect1>
     <refsect1>
       <title>Initial Value</title>
-      <para><symbol>nil</symbol></para>
+      <para>&nil;</para>
     </refsect1>
     <refsect1>
       <title>Description</title>
       <function>connect</function> as the default value of the
       <parameter>database-type</parameter> parameter.</para>
       <caution>
-        <para>If the value of this variable is <symbol>nil</symbol>,
+        <para>If the value of this variable is &nil;,
         then all calls to
         <function>initialize-database-type</function> or
         <function>connect</function> will have to specify the
       <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>
     </refsect1>
     <refsect1>
       <title>Initial Value</title>
-      <para><symbol>nil</symbol></para>
+      <para>&nil;</para>
     </refsect1>
     <refsect1>
       <title>Description</title>
       <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>
         <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>
           <listitem>
             <para>A boolean flag. If &t;, acquire connection from a
             pool of open connections. If the pool is empty, a new
-            connection is created. The default is &nil;. This is a
-            &clsql; extension.
+            connection is created. The default is &nil;. 
             </para>
           </listitem>
         </varlistentry>
             <para>A boolean flag. If &t;,
             <symbol>*default-database*</symbol> is set to the new
             connection, otherwise <symbol>*default-database*</symbol>
-            is not changed. The default is &t;. This is a &clsql;
-            extension.
+            is not changed. The default is &t;. 
             </para>
           </listitem>
         </varlistentry>
        <title>Affected by</title>
        <para>
        <simplelist>
-         <member><symbol>*default-database-type*</symbol></member>
-         <member><symbol>*connect-if-exists*</symbol></member>
+         <member>
+           <link linkend="default-database-type">
+             <symbol>*default-database-type*</symbol>
+           </link>
+         </member>
+         <member>
+           <link linkend="connect-if-exists">
+             <symbol>*connect-if-exists*</symbol>
+           </link>
+         </member>
        </simplelist>
        </para>
       </refsect1>
       </refsect1>
       <refsect1>
        <title>Notes</title>
-       <para>None.</para>
+       <para>The <parameter>pool</parameter> and
+       <parameter>make-default</parameter> keyword arguments to
+       <function>connect</function> are &clsql; extensions.</para>
       </refsect1>
     </refentry>
 
       <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>
       <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>
         <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>
       <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>
       <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>
            <term><parameter>error</parameter></term>
            <listitem>
              <para>A boolean flag indicating whether to signal an error 
-              if <parameter>database</parameter> is non-nil but cannot 
+              if <parameter>database</parameter> is non-&nil; but cannot 
               be found. 
               </para>
            </listitem>
        returned by <function>connect</function>, and closes the
        connection. If no matching database is found and
        <parameter>error</parameter> and
-       <parameter>database</parameter> are both non-nil an error is
-       signaled, otherwise nil is returned. If the database is from a
+       <parameter>database</parameter> are both non-&nil; an error is
+       signaled, otherwise &nil; is returned. If the database is from a
        pool it will be released to this pool.
         </para> 
 
       </refsect1>
       <refsect1>
        <title>Side Effects</title>
-       <para>The database connection is closed, and the database
-         object is removed from the list of connected databases as
-         returned by <function>connected-databases</function>.</para>
-       <para>The state of the database object is changed to
-       <type>closed</type>.</para>
+       <para>The database object is removed from the list of connected databases as
+         returned by <link linkend="connected-databases"><function>connected-databases</function></link>.</para>
        <para>If the database object passed is the same under
-       <function>eq</function> as the value of
-       <symbol>*default-database*</symbol>, then
-       <symbol>*default-database*</symbol> is set to the first
-       remaining database from
-       <function>connected-databases</function> or to nil if no
-       further active database exists.</para>
+         <function>eq</function> as the value of
+         <symbol>*default-database*</symbol>, then
+         <symbol>*default-database*</symbol> is set to the first
+         remaining database from
+         <function>connected-databases</function> or to &nil; if no
+         further active database exists.</para>
+       <refsect2>
+         <title>Non-pooled</title>
+         <para>The database connection is closed and the state of the
+         database object is changed to <type>closed</type>.</para>
+       </refsect2>
+       <refsect2>
+         <title>Pooled</title>
+         <para>Unless there are already <link linkend="db-pool-max-free-connections">
+             <symbol>*db-pool-max-free-connections*</symbol>
+           </link> free connections in the pool it is returned to the
+           pool, with the backend having an opportunity to run
+           generic cleanup on the connection first. If the max free
+           connections has already been reached then it is
+           disconnected as if it were not in the pool.
+         </para>
+       </refsect2>
       </refsect1>
       <refsect1>
        <title>Affected by</title>
        <para>
        <simplelist>
-         <member><symbol>*default-database*</symbol></member>
+         <member>
+           <link linkend="default-database">
+             <symbol>*default-database*</symbol>
+           </link>
+         </member>
+         <member>
+           <link linkend="db-pool-max-free-connections">
+             <symbol>*db-pool-max-free-connections*</symbol>
+           </link>
+         </member>
        </simplelist>
        </para>
       </refsect1>
         <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>
       <refsect1>
        <title>Syntax</title>
-       <synopsis><function>disconnect-pooled</function> => <returnvalue>t</returnvalue></synopsis>
+       <synopsis><function>disconnect-pooled</function> &amp;optional <symbol>clear</symbol> => <returnvalue>t</returnvalue></synopsis>
       </refsect1>
       <refsect1>
        <title>Description</title>
          linkend="connect"><function>connect</function></link> with 
           :pool &t;.
        </para>
+       <para>If optional argument <symbol>clear</symbol> is non-&nil;
+       then the connection-pool objects are also removed.</para>
       </refsect1>
       <refsect1>
        <title>Examples</title>
       </refsect1>
       <refsect1>
        <title>Side Effects</title>
-       <para>Database connections will be closed and entries in the pool are removed.
-       </para>
+       <para>Database connections will be closed and *all* entries in
+       the pool are removed. This is done with great prejudice and no
+       thought to thread safety or whether that connection is
+       currently in use.</para>
       </refsect1>
       <refsect1>
        <title>Affected by</title>
       <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>
            <term><parameter>db-type</parameter></term>
            <listitem>
              <para>
-                A keyword symbol denoting a known database back-end. This 
-                is a &clsql; extension. 
+                A keyword symbol denoting a known database back-end. 
               </para> 
            </listitem>
          </varlistentry>          
            <term><returnvalue>result</returnvalue></term>
            <listitem>
              <para>Either a database object, or, if
-               <parameter>errorp</parameter> is <symbol>nil</symbol>
-               possibly <symbol>nil</symbol>.</para>
+               <parameter>errorp</parameter> is &nil;
+               possibly &nil;.</para>
            </listitem>
          </varlistentry>
        </variablelist>
         <parameter>database</parameter>. If it succeeds, it returns
         the first database found.</para>
         <para> 
-          If <parameter>db-type</parameter> is nil all databases
+          If <parameter>db-type</parameter> is &nil; all databases
           matching the string <parameter>database</parameter> are
           considered. If no matching databases are found and
-          <parameter>errorp</parameter> is nil then nil is
-          returned. If <parameter>errorp</parameter> is nil and one or
+          <parameter>errorp</parameter> is &nil; then &nil; is
+          returned. If <parameter>errorp</parameter> is &nil; and one or
           more matching databases are found, then the most recently
           connected database is returned as a first value and the
           number of matching databases is returned as a second
       </refsect1>
       <refsect1>
        <title>Notes</title>
-       <para>None.</para>
+        <para>The <parameter>db-type</parameter> keyword argument to
+        <function>find-database</function> is a &clsql;
+        extension. </para>
       </refsect1>
     </refentry>
 
       <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>
         <varlistentry>
           <term><returnvalue>result</returnvalue></term>
           <listitem>
-            <para>Either <symbol>nil</symbol> if the initialization
+            <para>Either &nil; if the initialization
             attempt fails, or <symbol>t</symbol> otherwise.</para>
           </listitem>
         </varlistentry>
          <symbol>*initialized-database-types*</symbol>, if not
          already present.</para>
        <para>If initialization fails, the function returns
-         <symbol>nil</symbol>, and/or signals an error of type
+         &nil;, and/or signals an error of type
          <errortype>clsql-error</errortype>.  The kind of action
          taken depends on the back-end and the cause of the
          problem.</para>
       <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>
       database whose name matches <parameter>database</parameter> is
       sought in the list of connected databases. If no matching
       database is found and <parameter>error</parameter> and
-      <parameter>database</parameter> are both non-nil an error is
-      signaled, otherwise nil is returned.</para> 
+      <parameter>database</parameter> are both non-&nil; an error is
+      signaled, otherwise &nil; is returned.</para> 
 
       <para> When the current database connection has been lost, if
-      <parameter>force</parameter> is non-nil as it is by default, the
+      <parameter>force</parameter> is non-&nil; as it is by default, the
       connection is closed and errors are suppressed. If
-      <parameter>force</parameter> is nil and the database connection
+      <parameter>force</parameter> is &nil; and the database connection
       cannot be closed, an error is signalled.
       </para>
     </refsect1>
       <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>
       <title>Description</title>
       <para>Prints information about the currently connected databases
       to <symbol>*STANDARD-OUTPUT*</symbol>. The argument
-      <parameter>full</parameter> is nil by default and a value of t
+      <parameter>full</parameter> is &nil; by default and a value of t
       means that more detailed information about each database is
       printed.
       </para>
@@ -1612,7 +1707,7 @@ CLSQL STATUS: 2004-06-13 15:07:39
    localhost/test/petrov    mysql              nil        
    localhost/test/petrov    postgresql         nil        
    localhost/test/petrov    postgresql-socket  nil        
-   mysql-test/petrov        odbc               nil        
+   test/petrov              odbc               nil        
 *  :memory:                 sqlite             nil        
 --------------------------------------------------------
 
@@ -1676,7 +1771,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>
@@ -1774,7 +1869,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>
@@ -1825,7 +1920,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>
@@ -1871,7 +1966,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>
@@ -1954,7 +2049,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>
@@ -2052,7 +2147,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>
@@ -2068,7 +2163,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>
@@ -2082,7 +2177,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>
@@ -2168,7 +2268,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>
@@ -2206,8 +2306,9 @@ Error: While trying to access database localhost/test2/root
     </refsect1>
     <refsect1>
       <title>Description</title>
-      <para>Perform BODY with DATABASE bound as
-      *default-database*.
+      <para>Perform <parameter>body</parameter> with
+      <parameter>DATABASE</parameter> bound as
+      <symbol>*default-database*</symbol>.
       </para>
     </refsect1>
     <refsect1>