r9751: additional doc

diff --git a/doc/ref-oodml.xml b/doc/ref-oodml.xml
index 9b17eba7ee7da5c5a129e771fcad51b98ad6d228..4fbf5651ee29a5cc9319dc4f2f0ac14e7b4d22f5 100644 (file)
--- a/doc/ref-oodml.xml
+++ b/doc/ref-oodml.xml
@@ -10,7 +10,16 @@
   <title>Object Oriented Data Manipulation Language (OODML)</title> 
     <partintro>
     <para>
-      <!-- introduction --> 
+      Object Oriented Data Manipulation Language (OODML) provides a Common Lisp
+      Object System (CLOS) interface to SQL databases. View classes are defined with
+      the <link linkend="ref-ooddl">OODDL</link> interface and objects are read and
+      written with the OODML.
+    </para>
+    <para>
+      The main function for reading data with the OODML is the
+      <link linkend="select"><function>select</function></link> function. The
+      <function>select</function> is also used in the FDML. However, when <function>select</function>
+      is given a view class name, it returns a list of instances of view classes.
     </para>
   </partintro>
 
@@ -113,7 +122,7 @@
   <refentry id="delete-instance-records">
     <refnamediv>
       <refname>DELETE-INSTANCE-RECORDS</refname>
-      <refpurpose>Delete SQL records represented by a view class object</refpurpose>
+      <refpurpose>Delete SQL records represented by a view class object.</refpurpose>
       <refclass>Function</refclass>
     </refnamediv>
     <refsect1>
@@ -124,15 +133,23 @@
     <refsect1>
       <title>Arguments and Values</title>
       <variablelist>
-        <!-- arguments and values --> 
+       <varlistentry>
+         <term><parameter>object</parameter></term>
+         <listitem>
+           <para>
+             An instance of a view class.
+           </para>
+         </listitem>
+       </varlistentry>
       </variablelist>
     </refsect1>
     <refsect1>
       <title>Description</title>
-      <para>Deletes the records represented by OBJECT in the
-      appropriate table of the database associated with OBJECT. If
-      OBJECT is not yet associated with a database, an error is
-      signalled.
+      <para>Deletes the records represented by
+      <parameter>object</parameter> in the appropriate table of the
+      database associated with <parameter>object</parameter>. If
+      <parameter>object</parameter> is not yet associated with a
+      database, an error is signalled.
       </para>
     </refsect1>
     <refsect1>
@@ -144,8 +161,6 @@
                        (make-instance 'tab :a 5 :b "the string")))
        * (start-sql-recording :type :both)
         * (delete-instance-records obj)                
-           
-        
       </screen>
     </refsect1>
     <refsect1>
@@ -189,7 +204,7 @@
   <refentry id="instance-refreshed">
     <refnamediv>
       <refname>INSTANCE-REFRESHED</refname>
-      <refpurpose>Hook to call on object refresh</refpurpose>
+      <refpurpose>User hook to call on object refresh.</refpurpose>
       <refclass>Generic function</refclass>
     </refnamediv>
     <refsect1>
@@ -212,14 +227,16 @@
     </refsect1>
     <refsect1>
       <title>Description</title>
-      <para>Provides a hook which is called within an object
-      oriented call to SELECT with a non-nil value of REFRESH when
-      the View Class instance OBJECT has been updated from the
-      database. A method specialised on STANDARD-DB-OBJECT is
-      provided which has no effects. Methods specialised on
-      particular View Classes can be used to specify any operations
-      that need to be made on View Classes instances which have been
-      updated in calls to SELECT.
+      <para>Provides a hook which is called within an object oriented
+      call to <function>select</function> with a non-nil value of
+      <parameter>refresh</parameter> when the View Class instance
+      <parameter>object</parameter> has been updated from the
+      database. A method specialised on
+      <type>standard-db-object</type> is provided which has no
+      effects. Methods specialised on particular View Classes can be
+      used to specify any operations that need to be made on View
+      Classes instances which have been updated in calls to
+      <function>select</function>.
       </para>
     </refsect1>
     <refsect1>
@@ -231,15 +248,7 @@
     <refsect1>
       <title>Side Effects</title>
       <para>
-        <!-- side effects --> 
-      </para>
-    </refsect1>
-    <refsect1>
-      <title>Affected by</title>
-      <para>
-        <simplelist>
-          <!-- affected by --> 
-        </simplelist>
+        The user hook function may cause side effects.
       </para>
     </refsect1>
     <refsect1>
@@ -252,16 +261,10 @@
       <title>See Also</title>
       <para>
         <simplelist>
-          <!-- see also --> 
+         <member><link linkend="select"><function>select</function></link></member>
         </simplelist>
       </para>
     </refsect1>
-    <refsect1>
-      <title>Notes</title>
-      <para>
-        <!-- notes --> 
-      </para>
-    </refsect1>
   </refentry> 
 
   <refentry id="update-instance-from-records">
@@ -278,17 +281,34 @@
     <refsect1>
       <title>Arguments and Values</title>
       <variablelist>
-        <!-- arguments and values --> 
+       <varlistentry>
+         <term><parameter>object</parameter></term>
+         <listitem>
+           <para>
+             An instance of a view class.
+           </para>
+         </listitem>
+       </varlistentry>
+       <varlistentry>
+         <term><parameter>database</parameter></term>
+         <listitem>
+           <para>
+             A database connection.
+           </para>
+         </listitem>
+       </varlistentry>
       </variablelist>
     </refsect1>
     <refsect1>
       <title>Description</title>
       <para>Updates the slot values of the View Class instance
-      OBJECT using the attribute values of the appropriate table of
-      DATABASE which defaults to the database associated with OBJECT
-      or, if OBJECT is not associated with a database,
-      *DEFAULT-DATABASE*.  Join slots are updated but instances of
-      the class on which the join is made are not updated.
+      <parameter>object</parameter> using the attribute values of the
+      appropriate table of <parameter>database</parameter> which
+      defaults to the database associated with
+      <parameter>object</parameter> or, if <parameter>object</parameter> is not associated
+      with a database, <variable>*default-database*</variable>.  Join slots are updated but
+      instances of the class on which the join is made are not
+      updated.
       </para>
     </refsect1>
     <refsect1>
@@ -300,21 +320,21 @@
     <refsect1>
       <title>Side Effects</title>
       <para>
-        <!-- side effects --> 
+        Slot values of <parameter>object</parameter> may be modified.
       </para>
     </refsect1>
     <refsect1>
       <title>Affected by</title>
       <para>
         <simplelist>
-          <!-- affected by --> 
+         Data in SQL database.
         </simplelist>
       </para>
     </refsect1>
     <refsect1>
       <title>Exceptional Situations</title>
       <para>
-        <!-- execeptional situations -->
+        If <parameter>database</parameter> is not able to be read.
       </para>
     </refsect1>
     <refsect1>
@@ -336,7 +356,7 @@
   <refentry id="update-objects-joins">
     <refnamediv>
       <refname>UPDATE-OBJECTS-JOINS</refname>
-      <refpurpose>Updates joined slots of objects</refpurpose>
+      <refpurpose>Updates joined slots of objects.</refpurpose>
       <refclass>Function</refclass>
     </refnamediv>
     <refsect1>
@@ -347,26 +367,63 @@
     <refsect1>
       <title>Arguments and Values</title>
       <variablelist>
-        <!-- arguments and values --> 
+       <varlistentry>
+         <term><parameter>objects</parameter></term>
+         <listitem>
+           <para>
+             A list of instances of a view class.
+           </para>
+         </listitem>
+       </varlistentry>
+       <varlistentry>
+         <term><parameter>slots</parameter></term>
+         <listitem>
+           <para>
+           </para>
+         </listitem>
+       </varlistentry>
+       <varlistentry>
+         <term><parameter>force-p</parameter></term>
+         <listitem>
+           <para>
+           </para>
+         </listitem>
+       </varlistentry>
+       <varlistentry>
+         <term><parameter>class-name</parameter></term>
+         <listitem>
+           <para>
+             A list of instances of a view class.
+           </para>
+         </listitem>
+       </varlistentry>
+       <varlistentry>
+         <term><parameter>max-len</parameter></term>
+         <listitem>
+           <para>
+           </para>
+         </listitem>
+       </varlistentry>
       </variablelist>
     </refsect1>
     <refsect1>
       <title>Description</title>
-      <para>Updates from the records of the appropriate
-      database tables the join slots specified by SLOTS in
-      the supplied list of View Class instances OBJECTS.
-      SLOTS is t by default which means that all join slots
-      with :retrieval :immediate are updated. CLASS-NAME is
-      used to specify the View Class of all instance in
-      OBJECTS and default to nil which means that the class
-      of the first instance in OBJECTS is used. FORCE-P is t
-      by default which means that all join slots are updated
-      whereas a value of nil means that only unbound join
-      slots are updated. MAX-LEN defaults to
-      *DEFAULT-UPDATE-OBJECTS-MAX-LEN* and when non-nil
-      specifies that UPDATE-OBJECT-JOINS may issue multiple
-      database queries with a maximum of MAX-LEN instances
-      updated in each query.
+      <para>Updates from the records of the appropriate database
+      tables the join slots specified by <parameter>slots</parameter>
+      in the supplied list of View Class instances
+      <parameter>objects</parameter>. <parameter>slots</parameter>
+      when &t; means that all join slots with :retrieval :immediate
+      are updated. <parameter>class-name</parameter> is used to
+      specify the View Class of all instance in
+      <parameter>objects</parameter>, when &nil; then the class of the
+      first instance in <parameter>objects</parameter> is
+      used. <parameter>force-p</parameter> when &t; means that all
+      join slots are updated whereas a value of &nil; means that only
+      unbound join slots are updated. <parameter>max-len</parameter>
+      when non-nil specifies that
+      <function>update-object-joins</function> may issue multiple
+      database queries with a maximum of
+      <parameter>max-len</parameter> instances updated in each query.
       </para>
     </refsect1>
     <refsect1>
@@ -414,7 +471,7 @@
   <refentry id="update-record-from-slot">
     <refnamediv>
       <refname>UPDATE-RECORD-FROM-SLOT</refname>
-      <refpurpose>Updates database from slot value</refpurpose>
+      <refpurpose>Updates database from slot value.</refpurpose>
       <refclass>Function</refclass>
     </refnamediv>
     <refsect1>
@@ -430,31 +487,34 @@
     </refsect1>
     <refsect1>
       <title>Description</title>
-      <para>Updates the value stored in the column represented by
-      the slot, specified by the CLOS slot name SLOT, of View Class
-      instance OBJECT. DATABASE defaults to *DEFAULT-DATABASE* and
+      <para>Updates the value stored in the column represented by the
+      slot, specified by the CLOS slot name
+      <parameter>slot</parameter>, of View Class instance
+      <parameter>object</parameter>. <parameter>database</parameter>
       specifies the database in which the update is made only if
-      OBJECT is not associated with a database. In this case, a
-      record is created in DATABASE and the attribute represented by
-      SLOT is initialised from the value of the supplied slots with
-      other attributes having default values. Furthermore, OBJECT
-      becomes associated with DATABASE.
+      <parameter>object</parameter> is not associated with a
+      database. In this case, a record is created in
+      <parameter>database</parameter> and the attribute represented by
+      <parameter>slot</parameter> is initialised from the value of the
+      supplied slots with other attributes having default
+      values. Furthermore, <parameter>object</parameter> becomes
+      associated with <parameter>database</parameter>.
       </para>
     </refsect1>
     <refsect1>
-      <title>Examples</title>
+      <title>examples</title>
       <screen>
         <!-- examples -->
       </screen>
     </refsect1>
     <refsect1>
-      <title>Side Effects</title>
+      <title>side effects</title>
       <para>
-        <!-- side effects --> 
+        modifies sql database.
       </para>
     </refsect1>
     <refsect1>
-      <title>Affected by</title>
+      <title>affected by</title>
       <para>
         <simplelist>
           <!-- affected by --> 
@@ -462,13 +522,13 @@
       </para>
     </refsect1>
     <refsect1>
-      <title>Exceptional Situations</title>
+      <title>exceptional situations</title>
       <para>
-        <!-- execeptional situations -->
+        if a database error occurs.
       </para>
     </refsect1>
     <refsect1>
-      <title>See Also</title>
+      <title>see also</title>
       <para>
         <simplelist>
           <!-- see also --> 
@@ -476,7 +536,7 @@
       </para>
     </refsect1>
     <refsect1>
-      <title>Notes</title>
+      <title>notes</title>
       <para>
         <!-- notes --> 
       </para>
@@ -485,33 +545,35 @@
 
   <refentry id="update-record-from-slots">
     <refnamediv>
-      <refname>UPDATE-RECORD-FROM-SLOTS</refname>
-      <refpurpose>Update database from slots of view class object</refpurpose>
-      <refclass>Function</refclass>
+      <refname>update-record-from-slots</refname>
+      <refpurpose>update database from slots of view class object.</refpurpose>
+      <refclass>function</refclass>
     </refnamediv>
     <refsect1>
-      <title>Syntax</title>
+      <title>syntax</title>
       <synopsis>
-      <function>(update-record-from-slots object slots &amp;key database)</function> => <returnvalue><!-- result --></returnvalue></synopsis>
+      <function>(update-record-from-slots object slots &amp;key (database *default-database*))</function> => <returnvalue><!-- result --></returnvalue></synopsis>
     </refsect1>
     <refsect1>
-      <title>Arguments and Values</title>
+      <title>arguments and values</title>
       <variablelist>
         <!-- arguments and values --> 
       </variablelist>
     </refsect1>
     <refsect1>
-      <title>Description</title>
-      <para>Updates the values stored in the columns represented by
-      the slots, specified by the CLOS slot names SLOTS, of View
-      Class instance OBJECT. DATABASE defaults to *DEFAULT-DATABASE*
-      and specifies the database in which the update is made only if
-      OBJECT is not associated with a database. In this case, a
-      record is created in the appropriate table of DATABASE and the
-      attributes represented by SLOTS are initialised from the
-      values of the supplied slots with other attributes having
-      default values. Furthermore, OBJECT becomes associated with
-      DATABASE.
+      <title>description</title>
+      <para>updates the values stored in the columns represented by
+      the slots, specified by the clos slot names
+      <parameter>slots</parameter>, of view class instance
+      <parameter>object</parameter>. <parameter>database</parameter>
+      specifies the database in which the update is made only if
+      <parameter>object</parameter> is not associated with a
+      database. In this case, a record is created in the appropriate
+      table of <parameter>database</parameter> and the attributes
+      represented by <parameter>slots</parameter> are initialised from
+      the values of the supplied slots with other attributes having
+      default values. Furthermore, <parameter>object</parameter>
+      becomes associated with <parameter>database</parameter>.
       </para>
     </refsect1>
     <refsect1>
@@ -523,7 +585,7 @@
     <refsect1>
       <title>Side Effects</title>
       <para>
-        <!-- side effects --> 
+       Modifies the SQL database.
       </para>
     </refsect1>
     <refsect1>
@@ -566,7 +628,7 @@
     <refsect1>
       <title>Syntax</title>
       <synopsis>
-      <function>(update-records-from-instance object &amp;key database)</function> => <returnvalue><!-- result --></returnvalue></synopsis>
+      <function>(update-records-from-instance object &amp;key (database *default-database*))</function> => <returnvalue><!-- result --></returnvalue></synopsis>
     </refsect1>
     <refsect1>
       <title>Arguments and Values</title>
@@ -576,13 +638,16 @@
     </refsect1>
     <refsect1>
       <title>Description</title>
-      <para>Using an instance of a View Class, OBJECT, update the
-      table that stores its instance data. DATABASE defaults to
-      *DEFAULT-DATABASE* and specifies the database in which the
-      update is made only if OBJECT is not associated with a
+      <para>Using an instance of a View Class,
+      <parameter>object</parameter>, update the table that stores its
+      instance data. <parameter>database</parameter> specifies the
+      database in which the update is made only if
+      <parameter>object</parameter> is not associated with a
       database. In this case, a record is created in the appropriate
-      table of DATABASE using values from the slot values of OBJECT,
-      and OBJECT becomes associated with DATABASE.
+      table of <parameter>database</parameter> using values from the
+      slot values of <parameter>object</parameter>, and
+      <parameter>object</parameter> becomes associated with
+      <parameter>database</parameter>.
       </para>
     </refsect1>
     <refsect1>
@@ -636,7 +701,7 @@
     <refsect1>
       <title>Syntax</title>
       <synopsis>
-      <function>(update-slot-from-record object slot &amp;key database)</function> => <returnvalue><!-- result --></returnvalue></synopsis>
+      <function>(update-slot-from-record object slot &amp;key (database *default-database*))</function> => <returnvalue><!-- result --></returnvalue></synopsis>
     </refsect1>
     <refsect1>
       <title>Arguments and Values</title>
@@ -647,12 +712,15 @@
     <refsect1>
       <title>Description</title>
       <para>Updates the slot value, specified by the CLOS slot name
-      SLOT, of the View Class instance OBJECT using the attribute
-      values of the appropriate table of DATABASE which defaults to
-      the database associated with OBJECT or, if OBJECT is not
-      associated with a database, *DEFAULT-DATABASE*.  Join slots
-      are updated but instances of the class on which the join is
-      made are not updated.
+      <parameter>slot</parameter>, of the View Class instance
+      <parameter>object</parameter> using the attribute values of the
+      appropriate table of <parameter>database</parameter> which
+      defaults to the database associated with
+      <parameter>object</parameter> or, if
+      <parameter>object</parameter> is not associated with a database,
+      <variable>*default-database*</variable>.  Join slots are updated
+      but instances of the class on which the join is made are not
+      updated.
       </para>
     </refsect1>
     <refsect1>
@@ -664,21 +732,21 @@
     <refsect1>
       <title>Side Effects</title>
       <para>
-        <!-- side effects --> 
+       Modifies the slot value of the object.
       </para>
     </refsect1>
     <refsect1>
       <title>Affected by</title>
       <para>
         <simplelist>
-          <!-- affected by --> 
+         <member>Data in SQL database.</member>
         </simplelist>
       </para>
     </refsect1>
     <refsect1>
       <title>Exceptional Situations</title>
       <para>
-        <!-- execeptional situations -->
+       SQL access errors.
       </para>
     </refsect1>
     <refsect1>