X-Git-Url: http://git.kpe.io/?p=clsql.git;a=blobdiff_plain;f=doc%2Fintro.xml;h=1dc741dc954c7d3a3a1cb5a824e44983f1b44f23;hp=facffa7f67dbf08ef4bd9ed09d0af93274a26f3e;hb=55f590bf6f5298e59aae30f02c958388f483da02;hpb=bd57425b302d5c2e52732545f3f354a2f5f471cf

diff --git a/doc/intro.xml b/doc/intro.xml
index facffa7..1dc741d 100644
--- a/doc/intro.xml
+++ b/doc/intro.xml
@@ -1,7 +1,7 @@
 <?xml version='1.0' ?>
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
                "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
-<!ENTITY % myents SYSTEM "entities.xml">
+<!ENTITY % myents SYSTEM "entities.inc">
 %myents;
 ]>
 
@@ -11,44 +11,59 @@
   <sect1 id="purpose">
     <title>Purpose</title>
     <para>&clsql; is a Common Lisp interface to <glossterm
-      linkend="gloss-sql">SQL</glossterm> databases.  A number of Common
-      Lisp implementations and SQL databases are supported. The general
-      structure of &clsql; is based on the
-      <application>CommonSQL</application> 
-      package by Xanalys.
+    linkend="gloss-sql">SQL</glossterm> databases.  A number of Common
+    Lisp implementations and SQL databases are supported. The general
+    structure of &clsql; is based on the &commonsql; package by
+    LispWorks Ltd.
     </para>
   </sect1>
   
   <sect1 id="history">
     <title>History</title>
     <para>
-      &clsql; is written by Kevin M. Rosenberg and based substantially
-      on Pierre R. Mai's excellent &maisql; package. The main changes from &maisql;
-      are:
+      The &clsql; project was started by Kevin M. Rosenberg in 2001 to
+      support SQL access on multiple Common Lisp implementations using
+      the &uffi; library. The initial code was based substantially on
+      Pierre R. Mai's excellent &maisql; package. In late 2003, the
+      &usql; library was orphaned by its author, onShore Development,
+      Inc. In April 2004, Marcus Pearce ported the &usql; library to
+      &clsql;.  The &usql; library provides a &commonsql;-compatible
+      API for &clsql;.
+    </para>
+
+    <para>The main changes from &maisql; and &usql; are:
       <itemizedlist>
+	<listitem>
+	  <para>Port from the &cmucl; FFI to &uffi; which provide
+	  compatibility with the major Common Lisp
+	  implementations.</para>
+	</listitem>
 	<listitem>
 	  <para>Optimized loading of integer and floating-point fields.</para>
 	</listitem>
 	<listitem>
-	  <para>port from the &cmucl; FFI to &uffi;.</para>
+	  <para>Additional database backends: &odbc;, &aodbc;, &sqlite;
+	  and &sqlite3;.</para>
 	</listitem>
 	<listitem>
-	  <para>new &acl; ODBC interface back-end.</para>
+	  <para>A compatibility layer for &cmucl; specific code.</para>
 	</listitem>
 	<listitem>
-	  <para>compatibility layer for &cmucl; specific code.</para>
+	  <para>Much improved robustness for the &mysql; back-end
+	  along with version 4 client library support.</para>
 	</listitem>
 	<listitem>
-	  <para>much improved robustness for the &mysql; back-end.</para>
+	  <para>Improved library loading and installation documentation.</para>
 	</listitem>
 	<listitem>
-	  <para>improved system loading.</para>
+	  <para>Improved packages and symbol export.</para>
 	</listitem>
 	<listitem>
-	  <para>improved packages and symbol export.</para>
+	  <para>Pooled connections.</para>
 	</listitem>
 	<listitem>
-	  <para>transaction support.</para>
+	  <para>Integrated transaction support for the classic
+	  &maisql; iteration macros.</para>
 	</listitem>
       </itemizedlist>
     </para>
@@ -59,34 +74,30 @@
     
     <sect2>
       <title>&asdf;</title>
-      <para> &clsql; uses &asdf; to compile and load its
-	components.  &asdf; is included in the <ulink
-	url="http://cclan.sourceforge.net"><citetitle>&cclan;</citetitle></ulink> collection.
+      <para>
+	&clsql; uses &asdf; to compile and load its components.
+	&asdf; is included in the <ulink
+	url="http://cclan.sourceforge.net"><citetitle>&cclan;</citetitle></ulink>
+	collection.
       </para>
     </sect2>
     
     <sect2>
       <title>&uffi;</title>
-      <para>&clsql; uses <ulink
-	url="http://uffi.med-info.com/"><citetitle>&uffi;</citetitle></ulink>
-	as a <emphasis>Foreign Function Interface</emphasis> (<glossterm
-	linkend="gloss-ffi">FFI</glossterm>) to support multiple &cl;
-	implementations.
+      <para>
+	&clsql; uses <ulink
+	url="http://uffi.b9.com/"><citetitle>&uffi;</citetitle></ulink>
+	as a <emphasis>Foreign Function Interface</emphasis>
+	(<glossterm linkend="gloss-ffi">FFI</glossterm>) to support
+	multiple &cl; implementations.
       </para> 
-      
-      <para>You can download &uffi; from its FTP <ulink
-	url="ftp://ftp.med-info.com/pub/uffi/"><citetitle>site</citetitle></ulink>. There
-	are zip files for Microsoft Windows systems and gzipped tar files for
-	other systems.
-      </para>
     </sect2>
     
     <sect2>
       <title>&md5;</title>
       <para>&clsql;'s postgresql-socket interface uses Pierre Mai's 
-	<ulink url="ftp://clsql.b9.com/">md5</ulink>
-	module. If you plan to use
-	this interface please download the md5 module from ftp://clsql.b9.com.
+	<ulink url="ftp://files.b9.com/md5/">md5</ulink>
+	module.
       </para>       
     </sect2>
     <sect2>
@@ -96,12 +107,18 @@
 	implementations of &uffi;. The following implementations are supported:
       </para>
       <itemizedlist mark="opencircle">
-	<listitem><para>&acl; v6.2 on Debian Linux, FreeBSD 4.5, and Microsoft Windows XP.</para></listitem>
-	<listitem><para>&lw; v4.3 on Debian Linux and Microsoft Windows XP.</para></listitem>
-	<listitem><para>&cmucl; 18e on Debian Linux, FreeBSD 4.5, and Solaris 2.8.</para></listitem>
-	<listitem><para>&sbcl; 0.8.5 on Debian Linux.</para></listitem>
-	<listitem><para>&scl; 1.2 on Debian Linux.</para></listitem>
-	<listitem><para>&openmcl; 0.14 on Debian Linux PowerPC.</para></listitem>
+	<listitem><para>&acl; v6.2 and 7.0b on Debian Linux x86 &amp;
+	x86_64 &amp; PowerPC, FreeBSD 4.5, and Microsoft Windows
+	XP.</para></listitem>
+	<listitem><para>&lw; v4.3 on Debian Linux and Microsoft
+	Windows XP.</para></listitem>
+	<listitem><para>&cmucl; 18e on Debian Linux, FreeBSD 4.5, and
+	Solaris 2.8.</para></listitem>
+	<listitem><para>&sbcl; 0.8.5 on Debian
+	Linux.</para></listitem>
+	<listitem><para>&scl; 1.1.1 on Debian Linux.</para></listitem>
+	<listitem><para>&openmcl; 0.14 on Debian Linux
+	PowerPC.</para></listitem>
       </itemizedlist>
     </sect2>
     
@@ -111,9 +128,14 @@
 	Currently, &clsql; supports the following databases:
       </para>
       <itemizedlist mark="opencircle">
-	<listitem><para>&mysql; v3.23.51.</para></listitem>
-	<listitem><para>&postgresql; v7.2 with both direct API and TCP socket connections.</para></listitem>
-	<listitem><para>Allegro's ODBC interface (&aodbc;) using iODBC ODBC manager.</para></listitem>
+	<listitem><para>&mysql; v3.23.51 and v4.0.18.</para></listitem>
+	<listitem><para>&postgresql; v7.4 with both direct API and TCP
+	socket connections.</para></listitem>
+	<listitem><para>&sqlite;.</para></listitem>
+	<listitem><para>&sqlite3;.</para></listitem>
+	<listitem><para>Direct &odbc; interface.</para></listitem>
+        <listitem><para>&oracle; OCI.</para></listitem>
+	<listitem><para>Allegro's DB interface (&aodbc;).</para></listitem>
       </itemizedlist>
     </sect2>
     
@@ -139,7 +161,7 @@
 	implementations do not support 64-bit integers. Thus, C helper
 	libraries are required to break these 64-bit integers into two compatible
 	32-bit integers. The helper libraries reside in the directories
-	<filename>uffi/</filename> and <filename>db-mysql</filename>.
+	<filename>uffi</filename> and <filename>db-mysql</filename>.
       </para>
       
       <sect3>
@@ -156,17 +178,22 @@
       <sect3>
 	<title>&unix;</title>
 	<para>
-	  Files named <filename>Makefile</filename> are supplied for building the libraries
-	  under &unix;. However, the <filename>.asd</filename> automatically invoke
-	  the makefiles when necessary. So, manual building of the helper libraries
-	  is not necessary on &unix;.
+	  Files named <filename>Makefile</filename> are supplied for
+	  building the libraries under &unix;. Loading the
+	  <filename>.asd</filename> files automatically invokes
+	  <application>make</application> when necessary. So, manual
+	  building of the helper libraries is not necessary on most
+	  &unix; systems. However, the location of the &mysql; library
+	  files and include files may need to adjusted in
+	  <filename>db-mysql/Makefile</filename> on non-Debian
+	  systems.
 	</para>
       </sect3>
       
     </sect2>
     
     <sect2>
-      <title>Load &uffi;</title>
+      <title>Add &uffi; path</title>
       <para>
 	Unzip or untar the &uffi; distribution which creates a directory
 	for the &uffi; files. Add that directory to &asdf;'s <varname>asdf:*central-registry*</varname>.
@@ -176,58 +203,57 @@
 	directory.
 	<screen>
 (push #P"/usr/share/lisp/uffi/" asdf:*central-registry*)
-(asdf:operate 'asdf:load-op :uffi)
 	</screen>
       </para>
     </sect2>
    <sect2>
-     <title>Load &md5; module</title>
+     <title>Add &md5; path</title>
      <para>
-       If you plan to use the  clsql-postgresql-socket interface, you must load the md5 module.
-       Unzip or untar the cl-md5 distribution, which creates a directory for the cl-md5 files.
-       Add that directory to &asdf;'s <varname>asdf:*central-registry*</varname>. 
-       You can do that by pushing the pathname of the directory onto this variable.
-        The following example code assumes the cl-md5 files reside in the
-       <filename>/usr/share/lisp/cl-md5/</filename> 
-       directory.
+       If you plan to use the clsql-postgresql-socket interface, you
+       must load the md5 module.  Unzip or untar the cl-md5
+       distribution, which creates a directory for the cl-md5 files.
+       Add that directory to &asdf;'s
+       <varname>asdf:*central-registry*</varname>.  You can do that by
+       pushing the pathname of the directory onto this variable.  The
+       following example code assumes the cl-md5 files reside in the
+       <filename>/usr/share/lisp/cl-md5/</filename> directory.
        <screen>
 (push #P"/usr/share/lisp/cl-md5/" asdf:*central-registry*)
-(asdf:operate 'asdf:load-op :md5)
        </screen>
      </para>
    </sect2>
    
    <sect2>
-     <title>Load &clsql; modules</title>
+     <title>Add &clsql; path and load module</title>
      <para>
-       Unzip or untar the &clsql; distribution which creates a directory
-       for the &clsql; files. Add that directory to &asdf;'s <varname>asdf:*central-registry*</varname>.
-       You can do that by pushing the pathname of the directory onto this variable.
-       The following example code assumes the &clsql; files reside in the
-       <filename>/usr/share/lisp/clsql/</filename> 
-       directory. You need to load, at a minimum,
-       the main <symbol>:clsql</symbol> system and at least one interface system.
+       Unzip or untar the &clsql; distribution which creates a
+       directory for the &clsql; files. Add that directory to &asdf;'s
+       <varname>asdf:*central-registry*</varname>.  You can do that by
+       pushing the pathname of the directory onto this variable.  The
+       following example code assumes the &clsql; files reside in the
+       <filename>/usr/share/lisp/clsql/</filename> directory. You need
+       to load the <symbol>clsql</symbol> system.
+
 	<screen>
-(push #P"/usr/share/lisp/clsql/" asdf:*central-repository*)
-(asdf:operate 'asdf:load-op 'clsql-base)        ; base clsql package
-(asdf:operate 'asdf:load-op 'clsql-mysql)       ; MySQL interface
-(asdf:operate 'asdf:load-op 'clsql-postgresql)  ; PostgreSQL interface
-(asdf:operate 'asdf:load-op 'clsql-postgresql-socket) ; Socket PGSQL interface
-(asdf:operate 'asdf:load-op 'clsql-aodbc)       ; Allegro ODBC interface
-(asdf:operate 'asdf:load-op 'clsql)             ; main clsql package
+(push #P"/usr/share/lisp/clsql/" asdf:*central-registry*)
+(asdf:operate 'asdf:load-op 'clsql)                   ; main CLSQL package
 	</screen>
       </para>
     </sect2>
     
     <sect2>
-      <title>Run test suite</title>
+      <title>Run test suite (optional)</title>
       <para>
-	After loading &clsql;, you can execute the test suite. A configuration
-	file named <filename>.clsql-test.config</filename> must be created
-	in your home directory. There are instructures on the format of that file
-	in the <filename>tests/tests.lisp</filename> file in the &clsql;
-	source directory. After creating that file, you can run the test suite
-	with &asdf;:
+	The test suite can be executed using the &asdf;
+	<symbol>test-op</symbol> operator. If &clsql; has not been
+	loaded with <symbol>asdf:load-op</symbol>, the
+	<symbol>asdf:test-op</symbol> operator will automatically load
+	&clsql;. A configuration file named
+	<filename>.clsql-test.config</filename> must be created in
+	your home directory. There are instructures on the format of
+	that file in the <filename>tests/README</filename>. After
+	creating <filename>.clsql-test.config</filename>, you can run
+	the test suite with &asdf;:
 	<screen>
 	  (asdf:operate 'asdf:test-op 'clsql)
         </screen>