Changes to more broadly support auto-increment. new odbc-postgresql-database type

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

diff --git a/doc/ref-ooddl.xml b/doc/ref-ooddl.xml
index be98f6dc148bc7bbfebe7fb5a6b09c4c97500ebc..4a2cffa140b4600703290805f4e6352301b5af1d 100644 (file)
--- a/doc/ref-ooddl.xml
+++ b/doc/ref-ooddl.xml
@@ -589,12 +589,16 @@
          </listitem>
          <listitem>
            <para>
-             <parameter>:normalisedp</parameter> - specifies whether
-          this class uses normalised inheritance from parent classes.
-          Defaults to nil, i.e. non-normalised schemas. When true,
+             <parameter>:normalizedp</parameter> - specifies whether
+          this class uses normalized inheritance from parent classes.
+          Defaults to nil, i.e. non-normalized schemas. When true,
           SQL database tables that map to this class and parent
           classes are joined on their primary keys to get the full
-          set of database columns for this class.
+          set of database columns for this class.  This means that 
+          the primary key of the base class will be copied to all 
+          subclasses as we insert so that all parent classes of an 
+          instance will have the same value in their primary key slots
+          (see tests/ds-nodes.lisp and oodml.lisp)
            </para>
          </listitem>
        </itemizedlist>
@@ -616,15 +620,16 @@
        this class.
       </para>
 
-      <title>Normalised inheritance schemas</title>
+      <refsect2>
+      <title>Normalized inheritance schemas</title>
       <para>
-    Specifying that <symbol>:normalisedp</symbol> is <symbol>T</symbol>
-    tells &clsql; to normalise the database schema for inheritance.
+    Specifying that <symbol>:normalizedp</symbol> is <symbol>T</symbol>
+    tells &clsql; to normalize the database schema for inheritance.
     What this means is shown in the examples below.
       </para>
 
       <para>
-    With <symbol>:normalisedp</symbol> equal to <symbol>NIL</symbol>
+    With <symbol>:normalizedp</symbol> equal to <symbol>NIL</symbol>
     (the default) the class inheritance would result in the following:
       </para>
       <screen>
@@ -654,7 +659,7 @@ SQL table USER:
       </screen>
 
       <para>
-    Using <symbol>:normalisedp</symbol> <symbol>T</symbol>, both
+    Using <symbol>:normalizedp</symbol> <symbol>T</symbol>, both
     view-classes need a primary key to join them on:
       </para>
       <screen>
@@ -676,7 +681,7 @@ SQL table NODE:
   ((user-id :accessor user-id :initarg :user-id
             :type integer :db-kind :key :db-constraints (:not-null))
    (nick :accessor nick :initarg :nick :type (varchar 64)))
-  (:normalisedp t))
+  (:normalizedp t))
 
 SQL table USER:
 +---------+-------------+------+-----+---------+-------+
@@ -690,7 +695,7 @@ SQL table USER:
       <para>
         In this second case, all slots of the view-class 'node
         are also available in view-class 'user, and can be used
-        as one would expect. For example, with the above normalised
+        as one would expect. For example, with the above normalized
         view-classes 'node and 'user, and SQL tracing turned on:
       </para>
       <screen>
@@ -716,7 +721,26 @@ CLSQL> (title test-user)
 CLSQL> (nick test-user)
 "test-user"
       </screen>
+      <para>
+        Notes from a refactor of this code.
+
+        There are many assumptions that need to be met for normalized classes to work
+
+        * The each of the classes should have its own single key column (of a different name)
+          that will contain an identical value.  EG: node has a node-id, setting which
+          is a node has a node-id and a setting-id which must be equal.  You cannot use
+          node-id as the primary key on both tables (as I would have expected).  The exception
+          to this seems to be if your class has no slots at all, then you dont need to have a
+          single key column, because your class is fully represented in the db by its parent(s)
 
+        * more than one parent class per normalized class should be considered experimental
+          and untested (vaya con Dios)
+
+        * There are a few code paths that just dont pay any attention to normalized classes
+          eg: delete-records-for-instance
+
+      </para>
+      </refsect2>
     </refsect1>
     <refsect1>
       <title>Examples</title>