X-Git-Url: http://git.kpe.io/?a=blobdiff_plain;f=doc%2Fref-connect.xml;h=35b8cf56b30aef8a446c903a152db9d7763eaf54;hb=fd2493718d0e1114fcbe3dd578dab658ea383e81;hp=4bc296b3fa843278fd26b9d80963f55a4dec18f5;hpb=528064c179b6b74f0a9d6a43c42e71de3f0e9a3a;p=clsql.git

diff --git a/doc/ref-connect.xml b/doc/ref-connect.xml
index 4bc296b..35b8cf5 100644
--- 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,18 +131,18 @@
       <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>
@@ -160,13 +160,13 @@
       <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>
@@ -241,18 +241,18 @@
       <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>
@@ -261,7 +261,7 @@
       <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
@@ -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>
@@ -311,7 +311,7 @@
     </refsect1>
     <refsect1>
       <title>Initial Value</title>
-      <para><symbol>nil</symbol></para>
+      <para>&nil;</para>
     </refsect1>
     <refsect1>
       <title>Description</title>
@@ -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>
@@ -406,8 +405,7 @@
           <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>
@@ -417,8 +415,7 @@
             <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>
@@ -580,7 +577,9 @@
       </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>
 
@@ -589,7 +588,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 +680,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 +797,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 +910,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 +999,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>
@@ -1015,7 +1014,7 @@
 	    <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>
@@ -1044,8 +1043,8 @@
 	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> 
 
@@ -1077,7 +1076,7 @@
 	<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
+	<function>connected-databases</function> or to &nil; if no
 	further active database exists.</para>
       </refsect1>
       <refsect1>
@@ -1115,7 +1114,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 +1178,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>
@@ -1209,8 +1208,7 @@
 	    <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>          
@@ -1218,8 +1216,8 @@
 	    <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>
@@ -1240,11 +1238,11 @@
         <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
@@ -1321,7 +1319,9 @@
       </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>
 
@@ -1330,7 +1330,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>
@@ -1354,7 +1354,7 @@
         <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>
@@ -1373,7 +1373,7 @@
 	  <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>
@@ -1444,7 +1444,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>
@@ -1503,13 +1503,13 @@
       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>
@@ -1569,7 +1569,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>
@@ -1595,7 +1595,7 @@
       <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 +1612,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 +1676,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 +1774,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>
@@ -1871,7 +1871,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 +1954,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 +2052,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>
@@ -2168,7 +2168,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 +2206,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>