Documentation updates.

package.lisp

@@ -274,6 +274,7 @@
 	   CHECK-RDCT
 	   CMPS
 	   PRE-CHECK-RDCT
+	   RDCT
 	   TRIVIAL-HMEQ
 	   TRIVIAL-RDCT
 
@@ -409,11 +410,13 @@
 	   F
 	   DFFR
 	   DGNL
+	   G
 	   GMSM1
 	   GNRT
 	   GNRT-NAME
 	   GRIN
 	   GRML
+	   H
 	   I-ADD
 	   I-CMPS
 	   I-SBTR

src/effective-homology.lisp

@@ -22,18 +22,43 @@
 #+clisp(eval-when (:compile-toplevel :load-toplevel :execute)
          (setf (ext:package-lock :clos) t))
 
+
 (DEFUN RDCT (n)
   (declare (fixnum n))
-  "Retrieve the N-th user created reduction from the list *RDCT-LIST*.
+  "--------------------------------------------------------------[function-doc]
-Return NIL if it doesn't exist."
+RDCT
+Args: (n)
+Returns the N-th user-created reduction from the list *RDCT-LIST*. Returns NIL
+if it doesn't exist.
+------------------------------------------------------------------------------"
   (the (or null reduction)
        (find n *rdct-list* :key #'idnm)))
 
+
 (DEFUN BUILD-RDCT (&key f g h orgn)
   (declare
    (type morphism f g h)
    (list orgn))
-  "Create a reduction. Use this function instead of the generic MAKE-INSTANCE."
+  "--------------------------------------------------------------[function-doc]
+BUILD-RDCT
+Args: (&key f g h orgn)
+Returns an instance of the class REDUCTION. The keyword arguments are as
+follows:
+
+:F F, an object of type morphism representing the morphism f of a reduction
+
+:G G, an object of type morphism representing the morphism g of a reduction
+
+:H H, an object of type morphism representing the morphism h of a reduction
+
+:ORGN ORGN, a list containing a relevant and carefully chosen comment about
+            the origin of the chain complex. This comment should be unique
+            for a Kenzo session (between calls of CAT-INIT), as it is used
+            for caching purposes.
+
+Use this function instead of creating instances via the standard constructor
+MAKE-INSTANCE.
+------------------------------------------------------------------------------"
   (the reduction
        (progn
          (unless orgn
@@ -70,21 +95,42 @@ Return NIL if it doesn't exist."
 		 (push rdct *rdct-list*)
 		 rdct)))))))
 
+
 (DEFUN TRIVIAL-RDCT (chcm)
   (declare (type chain-complex chcm))
+  "--------------------------------------------------------------[function-doc]
+TRIVIAL-RDCT
+Args: (chcm)
+Builds the trivial reduction according to the following diagram, which
+involves the chain complex CHCM only:
+
+          Zero    s
+     C  ------->   C
+      ^
+    | |
+ Id | | Id
+    | |
+    v
+     C
+
+Zero is the zero morphism of degree 1 of C and Id is its identity morphism.
+
+See also: ZERO-MRPH, IDNT-MRPH.
+------------------------------------------------------------------------------"
   (build-rdct
    :f (idnt-mrph chcm)
    :g (idnt-mrph chcm)
-   :h (zero-mrph chcm chcm +1) 
+   :h (zero-mrph chcm chcm +1)
    :orgn `(trivial-rdct ,chcm)))
 
+
 ;;;
 ;;;  HOMOTOPY-EQUIVALENCES
 ;;;
 
 ;;(defgeneric build-hmeq (keyword lrdct &key &allow-other-keys)
-(DEFGENERIC BUILD-HMEQ (keyword lrdct &key)
+(DEFGENERIC BUILD-HMEQ (keyword lrdct &key))
-  (:documentation "needed by ECL"))
+
 
 (DEFMETHOD BUILD-HMEQ ((keyword1 (eql :lrdct)) lrdct &key rrdct orgn)
   (declare
@@ -167,6 +213,40 @@ Return NIL if it doesn't exist."
 ;; Functions.
 
 (DEFUN PRE-CHECK-RDCT (rdct)
+  "--------------------------------------------------------------[function-doc]
+PRE-CHECK-RDCT
+Args: (rdct)
+Assigns the following Lisp global variables, using morphisms from RDCT and the
+differentials and identity morphisms of the underlying chain complexes,
+according to these formulas:
+
+*TDD*         = d  ° d
+                 ^    ^
+                 C    C
+
+*BDD*         = d  ° d
+                 C    C
+
+*ID-FG*       = Id  - f ° g
+                  C
+
+*ID-GF-DH-HD* = Id  - g ° f - (d ° h + h ° d )
+                  ^             ^           ^
+                  C             C           C
+
+*HH*          = h ° h
+*FH*          = f ° h
+*HG*          = h ° g
+
+*DF-FD*       = d  ° f - f ° d
+                 C            ^
+                              C
+
+*DG-GD*       = d  ° g - g ° d
+                 ^            C
+                 C
+
+------------------------------------------------------------------------------"
   (declare (type reduction rdct))
   (with-slots (bcc tcc f g h) rdct
     (declare
@@ -192,6 +272,19 @@ Return NIL if it doesn't exist."
 
 
 (DEFUN CHECK-RDCT ()
+  "--------------------------------------------------------------[function-doc]
+CHECK-RDCT
+Args: ()
+Maps combinations of the top and bottom chain complexes of a reduction using
+the morphisms created by PRE-CHECK-RDCT. Having no parameters, the
+combinations must be provided via the Lisp global variables *TC* and *BC*,
+for the top and bottom chain complex, respectively. If the morphisms are
+coherent, the result of each mapping is a null combination.
+
+Note: This function is intended for interactive use. It pauses after each
+evaluation for the user to inspect the result. Resume execution, by pressing
+the <Enter> key.
+------------------------------------------------------------------------------"
   (dolist (cmbn '(*tc* *bc*))
     (declare (type symbol cmbn))
     (format t "~%~A => ~A" cmbn (eval cmbn)))
@@ -206,6 +299,7 @@ Return NIL if it doesn't exist."
     (read-line))
   (done))
 
+
 (DEFMETHOD CMPS ((brdct reduction) (trdct reduction) &optional dummy)
   (declare (ignore dummy))
   (when (eq (first (orgn brdct)) 'trivial-rdct)

src/macros.lisp

@@ -254,6 +254,17 @@ See also the macro ?.
 ;;;
 
 (DEFMACRO BCC (&rest rest)
+  "-----------------------------------------------------------------[macro-doc]
+BCC
+Args: (&rest rest)
+Args: (rdct)
+Args: (rdct cmbn)
+Args: (rdct degr gnrt)
+With only one argument, a reduction RDCT, this macro returns the bottom
+chain complex of the reduction. Otherwise, it applies the differential of
+the bottom chain complex of RDCT to a combination provided in additional
+arguments such as CMBN or DEGR GNRT.
+------------------------------------------------------------------------------"
   (case (length rest)
     (1 `(bcc1 ,@rest))
     (otherwise
@@ -261,6 +272,17 @@ See also the macro ?.
 
 
 (DEFMACRO TCC (&rest rest)
+  "-----------------------------------------------------------------[macro-doc]
+TCC
+Args: (&rest rest)
+Args: (rdct)
+Args: (rdct cmbn)
+Args: (rdct degr gnrt)
+With only one argument, a reduction RDCT, this macro returns the top
+chain complex of the reduction. Otherwise, it applies the differential of
+the top chain complex of RDCT to a combination provided in additional
+arguments such as CMBN or DEGR GNRT.
+------------------------------------------------------------------------------"
   (case (length rest)
     (1 `(tcc1 ,@rest))
     (otherwise
@@ -268,6 +290,16 @@ See also the macro ?.
 
 
 (DEFMACRO F (&rest rest)
+  "-----------------------------------------------------------------[macro-doc]
+F
+Args: (&rest rest)
+Args: (rdct)
+Args: (rdct cmbn)
+Args: (rdct degr gnrt)
+With only one argument, a reduction RDCT, this macro returns the morphism f
+of the reduction. Otherwise, it applies f to a combination provided in
+additional arguments such as CMBN or DEGR GNRT.
+------------------------------------------------------------------------------"
   (case (length rest)
     (1 `(f1 ,@rest))
     (otherwise
@@ -275,6 +307,16 @@ See also the macro ?.
 
 
 (DEFMACRO G (&rest rest)
+  "-----------------------------------------------------------------[macro-doc]
+G
+Args: (&rest rest)
+Args: (rdct)
+Args: (rdct cmbn)
+Args: (rdct degr gnrt)
+With only one argument, a reduction RDCT, this macro returns the morphism g
+of the reduction. Otherwise, it applies g to a combination provided in
+additional arguments such as CMBN or DEGR GNRT.
+------------------------------------------------------------------------------"
   (case (length rest)
     (1 `(g1 ,@rest))
     (otherwise
@@ -282,6 +324,16 @@ See also the macro ?.
 
 
 (DEFMACRO H (&rest rest)
+  "-----------------------------------------------------------------[macro-doc]
+H
+Args: (&rest rest)
+Args: (rdct)
+Args: (rdct cmbn)
+Args: (rdct degr gnrt)
+With only one argument, a reduction RDCT, this macro returns the morphism h
+of the reduction. Otherwise, it applies h to a combination provided in
+additional arguments such as CMBN or DEGR GNRT.
+------------------------------------------------------------------------------"
   (case (length rest)
     (1 `(h1 ,@rest))
     (otherwise