From acbfa1ba2cf19a7cc3f9d55a407440be30c27fac Mon Sep 17 00:00:00 2001
From: Gerd Heber <gheber@hdfgroup.org>
Date: Sun, 8 Nov 2015 19:48:31 -0600
Subject: [PATCH] Resolved issue #67.

---
 examples/Chapter1.ipynb | 705 ++++++++++++++++++++++------------------
 src/macros.lisp         |  10 +
 2 files changed, 392 insertions(+), 323 deletions(-)

diff --git a/examples/Chapter1.ipynb b/examples/Chapter1.ipynb
index f0aba9f..36bdacf 100644
--- a/examples/Chapter1.ipynb
+++ b/examples/Chapter1.ipynb
@@ -22,7 +22,7 @@
       "  Load 1 ASDF system:\n",
       "    kenzo\n",
       "; Loading \"kenzo\"\n",
-      ".\n"
+      "\n"
      ]
     },
     {
@@ -337,6 +337,13 @@
     "(cat:cmbn-non-zero-p comb1)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The reader function $\\texttt{cat:cmbn-list}$ gets the list of terms of the combination $\\texttt{cmbn}$. Beware: a term is not a Kenzo object."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 13,
@@ -391,7 +398,11 @@
     {
      "data": {
       "text/plain": [
-       "3"
+       "\"-----------------------------------------------------------------[macro-doc]\n",
+       "CFFC\n",
+       "Args: (term)\n",
+       "Returns the the coefficient (integer) of a term.\n",
+       "------------------------------------------------------------------------------\""
       ]
      },
      "execution_count": 15,
@@ -400,7 +411,7 @@
     }
    ],
    "source": [
-    "(cat:cffc term3)"
+    "(documentation 'cat:cffc 'function)"
    ]
   },
   {
@@ -413,7 +424,7 @@
     {
      "data": {
       "text/plain": [
-       "W"
+       "3"
       ]
      },
      "execution_count": 16,
@@ -421,13 +432,61 @@
      "output_type": "execute_result"
     }
    ],
+   "source": [
+    "(cat:cffc term3)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 17,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "\"-----------------------------------------------------------------[macro-doc]\n",
+       "GNRT\n",
+       "Args: (term)\n",
+       "Returns the the generator of a term.\n",
+       "------------------------------------------------------------------------------\""
+      ]
+     },
+     "execution_count": 17,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "(documentation 'cat:gnrt 'function)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 18,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "W"
+      ]
+     },
+     "execution_count": 18,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
    "source": [
     "(cat:gnrt term3)"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 17,
+   "execution_count": 19,
    "metadata": {
     "collapsed": false
    },
@@ -442,7 +501,7 @@
        "------------------------------------------------------------------------------\""
       ]
      },
-     "execution_count": 17,
+     "execution_count": 19,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -453,7 +512,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 18,
+   "execution_count": 20,
    "metadata": {
     "collapsed": false
    },
@@ -470,7 +529,7 @@
        "------------------------------------------------------------------------------\n"
       ]
      },
-     "execution_count": 18,
+     "execution_count": 20,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -481,7 +540,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 19,
+   "execution_count": 21,
    "metadata": {
     "collapsed": false
    },
@@ -496,7 +555,7 @@
        "------------------------------------------------------------------------------\""
       ]
      },
-     "execution_count": 19,
+     "execution_count": 21,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -507,7 +566,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 20,
+   "execution_count": 22,
    "metadata": {
     "collapsed": false
    },
@@ -524,7 +583,7 @@
        "------------------------------------------------------------------------------\n"
       ]
      },
-     "execution_count": 20,
+     "execution_count": 22,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -535,7 +594,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 21,
+   "execution_count": 23,
    "metadata": {
     "collapsed": false
    },
@@ -553,7 +612,7 @@
        "------------------------------------------------------------------------------\""
       ]
      },
-     "execution_count": 21,
+     "execution_count": 23,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -564,7 +623,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 22,
+   "execution_count": 24,
    "metadata": {
     "collapsed": false
    },
@@ -581,7 +640,7 @@
        "------------------------------------------------------------------------------\n"
       ]
      },
-     "execution_count": 22,
+     "execution_count": 24,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -592,7 +651,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 23,
+   "execution_count": 25,
    "metadata": {
     "collapsed": false
    },
@@ -610,7 +669,7 @@
        "------------------------------------------------------------------------------\""
       ]
      },
-     "execution_count": 23,
+     "execution_count": 25,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -621,7 +680,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 24,
+   "execution_count": 26,
    "metadata": {
     "collapsed": false
    },
@@ -638,7 +697,7 @@
        "------------------------------------------------------------------------------\""
       ]
      },
-     "execution_count": 24,
+     "execution_count": 26,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -649,7 +708,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 25,
+   "execution_count": 27,
    "metadata": {
     "collapsed": false
    },
@@ -666,7 +725,7 @@
        "------------------------------------------------------------------------------\n"
       ]
      },
-     "execution_count": 25,
+     "execution_count": 27,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -692,7 +751,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 26,
+   "execution_count": 28,
    "metadata": {
     "collapsed": false
    },
@@ -700,10 +759,10 @@
     {
      "data": {
       "text/plain": [
-       "#<Compiled-function CAT:S-CMPR #x1510B576>"
+       "#<Compiled-function CAT:S-CMPR #x15064DDE>"
       ]
      },
-     "execution_count": 26,
+     "execution_count": 28,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -714,7 +773,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 27,
+   "execution_count": 29,
    "metadata": {
     "collapsed": false
    },
@@ -722,10 +781,10 @@
     {
      "data": {
       "text/plain": [
-       "#<Anonymous Function #x152BEA4E>"
+       "#<Anonymous Function #x1521F1EE>"
       ]
      },
-     "execution_count": 27,
+     "execution_count": 29,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -741,7 +800,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 28,
+   "execution_count": 30,
    "metadata": {
     "collapsed": false
    },
@@ -752,7 +811,7 @@
        "S0"
       ]
      },
-     "execution_count": 28,
+     "execution_count": 30,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -763,7 +822,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 29,
+   "execution_count": 31,
    "metadata": {
     "collapsed": false
    },
@@ -771,10 +830,10 @@
     {
      "data": {
       "text/plain": [
-       "#<Anonymous Function #x152CDB0E>"
+       "#<Anonymous Function #x15229B46>"
       ]
      },
-     "execution_count": 29,
+     "execution_count": 31,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -801,7 +860,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 30,
+   "execution_count": 32,
    "metadata": {
     "collapsed": false
    },
@@ -812,7 +871,7 @@
        ":GNRT"
       ]
      },
-     "execution_count": 30,
+     "execution_count": 32,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -823,7 +882,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 31,
+   "execution_count": 33,
    "metadata": {
     "collapsed": false
    },
@@ -834,7 +893,7 @@
        "(DIABOLO-FOR-EXAMPLE)"
       ]
      },
-     "execution_count": 31,
+     "execution_count": 33,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -845,7 +904,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 32,
+   "execution_count": 34,
    "metadata": {
     "collapsed": false
    },
@@ -883,64 +942,13 @@
        "------------------------------------------------------------------------------\""
       ]
      },
-     "execution_count": 32,
-     "metadata": {},
-     "output_type": "execute_result"
-    }
-   ],
-   "source": [
-    "(documentation 'cat:build-chcm 'function)"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 33,
-   "metadata": {
-    "collapsed": false
-   },
-   "outputs": [
-    {
-     "data": {
-      "text/plain": [
-       "[K1 Chain-Complex]"
-      ]
-     },
-     "execution_count": 33,
-     "metadata": {},
-     "output_type": "execute_result"
-    }
-   ],
-   "source": [
-    "(cat:def diabolo (cat:build-chcm :cmpr diabolo-cmpr :basis diabolo-basis\n",
-    "                                 :bsgn diabolo-bspn :intr-dffr diabolo-pure-dffr\n",
-    "                                 :strt diabolo-strt :orgn diabolo-orgn))"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 34,
-   "metadata": {
-    "collapsed": false
-   },
-   "outputs": [
-    {
-     "data": {
-      "text/plain": [
-       "\"--------------------------------------------------------------[function-doc]\n",
-       "CHCM\n",
-       "Args: (idnm)\n",
-       "Return from the list *CHCM-LIST* the chain complex instance with Kenzo\n",
-       "identifier IDNUM or NIL, if it doesn't exist.\n",
-       "------------------------------------------------------------------------------\""
-      ]
-     },
      "execution_count": 34,
      "metadata": {},
      "output_type": "execute_result"
     }
    ],
    "source": [
-    "(documentation 'cat:chcm 'function)"
+    "(documentation 'cat:build-chcm 'function)"
    ]
   },
   {
@@ -962,7 +970,9 @@
     }
    ],
    "source": [
-    "(cat:chcm 1)"
+    "(cat:def diabolo (cat:build-chcm :cmpr diabolo-cmpr :basis diabolo-basis\n",
+    "                                 :bsgn diabolo-bspn :intr-dffr diabolo-pure-dffr\n",
+    "                                 :strt diabolo-strt :orgn diabolo-orgn))"
    ]
   },
   {
@@ -975,7 +985,12 @@
     {
      "data": {
       "text/plain": [
-       "(DIABOLO-FOR-EXAMPLE)"
+       "\"--------------------------------------------------------------[function-doc]\n",
+       "CHCM\n",
+       "Args: (idnm)\n",
+       "Return from the list *CHCM-LIST* the chain complex instance with Kenzo\n",
+       "identifier IDNUM or NIL, if it doesn't exist.\n",
+       "------------------------------------------------------------------------------\""
       ]
      },
      "execution_count": 36,
@@ -984,7 +999,7 @@
     }
    ],
    "source": [
-    "(cat:orgn diabolo)"
+    "(documentation 'cat:chcm 'function)"
    ]
   },
   {
@@ -997,7 +1012,7 @@
     {
      "data": {
       "text/plain": [
-       "1"
+       "[K1 Chain-Complex]"
       ]
      },
      "execution_count": 37,
@@ -1006,7 +1021,7 @@
     }
    ],
    "source": [
-    "(cat:idnm diabolo)"
+    "(cat:chcm 1)"
    ]
   },
   {
@@ -1019,7 +1034,7 @@
     {
      "data": {
       "text/plain": [
-       "(S0 S1 S2 S3 S4 S5)"
+       "(DIABOLO-FOR-EXAMPLE)"
       ]
      },
      "execution_count": 38,
@@ -1028,7 +1043,7 @@
     }
    ],
    "source": [
-    "(cat:basis diabolo 0)"
+    "(cat:orgn diabolo)"
    ]
   },
   {
@@ -1041,7 +1056,7 @@
     {
      "data": {
       "text/plain": [
-       "(S01 S02 S12 S23 S34 S35 S45)"
+       "1"
       ]
      },
      "execution_count": 39,
@@ -1050,7 +1065,7 @@
     }
    ],
    "source": [
-    "(cat:basis diabolo 1)"
+    "(cat:idnm diabolo)"
    ]
   },
   {
@@ -1063,7 +1078,7 @@
     {
      "data": {
       "text/plain": [
-       "(S345)"
+       "(S0 S1 S2 S3 S4 S5)"
       ]
      },
      "execution_count": 40,
@@ -1072,7 +1087,7 @@
     }
    ],
    "source": [
-    "(cat:basis diabolo 2)"
+    "(cat:basis diabolo 0)"
    ]
   },
   {
@@ -1085,7 +1100,7 @@
     {
      "data": {
       "text/plain": [
-       "NIL"
+       "(S01 S02 S12 S23 S34 S35 S45)"
       ]
      },
      "execution_count": 41,
@@ -1093,13 +1108,57 @@
      "output_type": "execute_result"
     }
    ],
+   "source": [
+    "(cat:basis diabolo 1)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 42,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "(S345)"
+      ]
+     },
+     "execution_count": 42,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "(cat:basis diabolo 2)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 43,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "NIL"
+      ]
+     },
+     "execution_count": 43,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
    "source": [
     "(cat:basis diabolo 10)"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 42,
+   "execution_count": 44,
    "metadata": {
     "collapsed": false
    },
@@ -1115,7 +1174,7 @@
        "------------------------------------------------------------------------------\n"
       ]
      },
-     "execution_count": 42,
+     "execution_count": 44,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -1126,7 +1185,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 43,
+   "execution_count": 45,
    "metadata": {
     "collapsed": false
    },
@@ -1139,7 +1198,7 @@
        "------------------------------------------------------------------------------\n"
       ]
      },
-     "execution_count": 43,
+     "execution_count": 45,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -1157,7 +1216,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 44,
+   "execution_count": 46,
    "metadata": {
     "collapsed": false
    },
@@ -1168,7 +1227,7 @@
        "[K3 Chain-Complex]"
       ]
      },
-     "execution_count": 44,
+     "execution_count": 46,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -1192,7 +1251,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 45,
+   "execution_count": 47,
    "metadata": {
     "collapsed": false
    },
@@ -1207,7 +1266,7 @@
        "------------------------------------------------------------------------------\""
       ]
      },
-     "execution_count": 45,
+     "execution_count": 47,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -1225,7 +1284,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 46,
+   "execution_count": 48,
    "metadata": {
     "collapsed": false
    },
@@ -1236,7 +1295,7 @@
        "CIRCLE"
       ]
      },
-     "execution_count": 46,
+     "execution_count": 48,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -1267,7 +1326,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 47,
+   "execution_count": 49,
    "metadata": {
     "collapsed": false
    },
@@ -1324,7 +1383,7 @@
        "-----------------------------------------------------------------------------\""
       ]
      },
-     "execution_count": 47,
+     "execution_count": 49,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -1342,7 +1401,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 48,
+   "execution_count": 50,
    "metadata": {
     "collapsed": false
    },
@@ -1378,7 +1437,7 @@
        "------------------------------------------------------------------------------\""
       ]
      },
-     "execution_count": 48,
+     "execution_count": 50,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -1396,7 +1455,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 49,
+   "execution_count": 51,
    "metadata": {
     "collapsed": false
    },
@@ -1415,7 +1474,7 @@
        "NIL"
       ]
      },
-     "execution_count": 49,
+     "execution_count": 51,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -1426,7 +1485,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 50,
+   "execution_count": 52,
    "metadata": {
     "collapsed": false
    },
@@ -1437,7 +1496,7 @@
        "[K1 Chain-Complex]"
       ]
      },
-     "execution_count": 50,
+     "execution_count": 52,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -1448,7 +1507,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 51,
+   "execution_count": 53,
    "metadata": {
     "collapsed": false
    },
@@ -1459,7 +1518,7 @@
        "[K3 Cohomology-Class on K1 of degree 1]"
       ]
      },
-     "execution_count": 51,
+     "execution_count": 53,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -1476,7 +1535,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 52,
+   "execution_count": 54,
    "metadata": {
     "collapsed": false
    },
@@ -1487,7 +1546,7 @@
        "[K4 Cohomology-Class on K1 of degree 0]"
       ]
      },
-     "execution_count": 52,
+     "execution_count": 54,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -1510,7 +1569,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 53,
+   "execution_count": 55,
    "metadata": {
     "collapsed": false
    },
@@ -1518,10 +1577,10 @@
     {
      "data": {
       "text/plain": [
-       "#<Anonymous Function #x153443A6>"
+       "#<Anonymous Function #x151DDFE6>"
       ]
      },
-     "execution_count": 53,
+     "execution_count": 55,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -1535,7 +1594,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 54,
+   "execution_count": 56,
    "metadata": {
     "collapsed": false
    },
@@ -1546,7 +1605,7 @@
        "[K5 Chain-Complex]"
       ]
      },
-     "execution_count": 54,
+     "execution_count": 56,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -1562,7 +1621,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 55,
+   "execution_count": 57,
    "metadata": {
     "collapsed": false
    },
@@ -1573,7 +1632,7 @@
        "[K7 Morphism (degree 1): K5 -> K5]"
       ]
      },
-     "execution_count": 55,
+     "execution_count": 57,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -1587,7 +1646,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 56,
+   "execution_count": 58,
    "metadata": {
     "collapsed": false
    },
@@ -1598,7 +1657,7 @@
        "[K8 Morphism (degree -1): K5 -> K5]"
       ]
      },
-     "execution_count": 56,
+     "execution_count": 58,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -1612,7 +1671,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 57,
+   "execution_count": 59,
    "metadata": {
     "collapsed": false
    },
@@ -1626,7 +1685,7 @@
        "------------------------------------------------------------------------------\n"
       ]
      },
-     "execution_count": 57,
+     "execution_count": 59,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -1637,7 +1696,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 58,
+   "execution_count": 60,
    "metadata": {
     "collapsed": false
    },
@@ -1650,7 +1709,7 @@
        "------------------------------------------------------------------------------\n"
       ]
      },
-     "execution_count": 58,
+     "execution_count": 60,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -1661,7 +1720,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 59,
+   "execution_count": 61,
    "metadata": {
     "collapsed": false
    },
@@ -1677,7 +1736,7 @@
        "------------------------------------------------------------------------------\n"
       ]
      },
-     "execution_count": 59,
+     "execution_count": 61,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -1688,7 +1747,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 60,
+   "execution_count": 62,
    "metadata": {
     "collapsed": false
    },
@@ -1703,62 +1762,13 @@
        "------------------------------------------------------------------------------\n"
       ]
      },
-     "execution_count": 60,
-     "metadata": {},
-     "output_type": "execute_result"
-    }
-   ],
-   "source": [
-    "(cat:? ccn combn)"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 61,
-   "metadata": {
-    "collapsed": false
-   },
-   "outputs": [
-    {
-     "data": {
-      "text/plain": [
-       "\n",
-       "----------------------------------------------------------------------{CMBN 3}\n",
-       "------------------------------------------------------------------------------\n"
-      ]
-     },
-     "execution_count": 61,
-     "metadata": {},
-     "output_type": "execute_result"
-    }
-   ],
-   "source": [
-    "(cat:? ccn (cat:? ccn combn))"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 62,
-   "metadata": {
-    "collapsed": false
-   },
-   "outputs": [
-    {
-     "data": {
-      "text/plain": [
-       "\n",
-       "----------------------------------------------------------------------{CMBN 1}\n",
-       "<1 * 16>\n",
-       "------------------------------------------------------------------------------\n"
-      ]
-     },
      "execution_count": 62,
      "metadata": {},
      "output_type": "execute_result"
     }
    ],
    "source": [
-    "(cat:? upper-shift 0 6)"
+    "(cat:? ccn combn)"
    ]
   },
   {
@@ -1772,8 +1782,7 @@
      "data": {
       "text/plain": [
        "\n",
-       "----------------------------------------------------------------------{CMBN 4}\n",
-       "<1 * 41>\n",
+       "----------------------------------------------------------------------{CMBN 3}\n",
        "------------------------------------------------------------------------------\n"
       ]
      },
@@ -1783,7 +1792,7 @@
     }
    ],
    "source": [
-    "(cat:? lower-shift 5 51)"
+    "(cat:? ccn (cat:? ccn combn))"
    ]
   },
   {
@@ -1797,8 +1806,8 @@
      "data": {
       "text/plain": [
        "\n",
-       "----------------------------------------------------------------------{CMBN 3}\n",
-       "<1 * 31>\n",
+       "----------------------------------------------------------------------{CMBN 1}\n",
+       "<1 * 16>\n",
        "------------------------------------------------------------------------------\n"
       ]
      },
@@ -1808,7 +1817,7 @@
     }
    ],
    "source": [
-    "(cat:? lower-shift (cat:? lower-shift 5 51))"
+    "(cat:? upper-shift 0 6)"
    ]
   },
   {
@@ -1822,11 +1831,8 @@
      "data": {
       "text/plain": [
        "\n",
-       "----------------------------------------------------------------------{CMBN 1}\n",
-       "<1 * 10>\n",
-       "<2 * 11>\n",
-       "<3 * 12>\n",
-       "<4 * 13>\n",
+       "----------------------------------------------------------------------{CMBN 4}\n",
+       "<1 * 41>\n",
        "------------------------------------------------------------------------------\n"
       ]
      },
@@ -1836,7 +1842,7 @@
     }
    ],
    "source": [
-    "(cat:def comb1 (cat:cmbn 1 1 10 2 11 3 12 4 13))"
+    "(cat:? lower-shift 5 51)"
    ]
   },
   {
@@ -1849,7 +1855,10 @@
     {
      "data": {
       "text/plain": [
-       "[K9 Morphism (degree 0): K5 -> K5]"
+       "\n",
+       "----------------------------------------------------------------------{CMBN 3}\n",
+       "<1 * 31>\n",
+       "------------------------------------------------------------------------------\n"
       ]
      },
      "execution_count": 66,
@@ -1858,7 +1867,7 @@
     }
    ],
    "source": [
-    "(cat:def identity? (cat:cmps upper-shift lower-shift))"
+    "(cat:? lower-shift (cat:? lower-shift 5 51))"
    ]
   },
   {
@@ -1867,28 +1876,6 @@
    "metadata": {
     "collapsed": false
    },
-   "outputs": [
-    {
-     "data": {
-      "text/plain": [
-       "0"
-      ]
-     },
-     "execution_count": 67,
-     "metadata": {},
-     "output_type": "execute_result"
-    }
-   ],
-   "source": [
-    "(cat:degr identity?)"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 68,
-   "metadata": {
-    "collapsed": false
-   },
    "outputs": [
     {
      "data": {
@@ -1902,13 +1889,35 @@
        "------------------------------------------------------------------------------\n"
       ]
      },
+     "execution_count": 67,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "(cat:def comb1 (cat:cmbn 1 1 10 2 11 3 12 4 13))"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 68,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "[K9 Morphism (degree 0): K5 -> K5]"
+      ]
+     },
      "execution_count": 68,
      "metadata": {},
      "output_type": "execute_result"
     }
    ],
    "source": [
-    "(cat:? identity? comb1)"
+    "(cat:def identity? (cat:cmps upper-shift lower-shift))"
    ]
   },
   {
@@ -1921,9 +1930,7 @@
     {
      "data": {
       "text/plain": [
-       "\n",
-       "----------------------------------------------------------------------{CMBN 1}\n",
-       "------------------------------------------------------------------------------\n"
+       "0"
       ]
      },
      "execution_count": 69,
@@ -1932,7 +1939,7 @@
     }
    ],
    "source": [
-    "(cat:2cmbn-sbtr (cat:cmpr ccn) comb1 (cat:? identity? comb1))"
+    "(cat:degr identity?)"
    ]
   },
   {
@@ -1945,7 +1952,13 @@
     {
      "data": {
       "text/plain": [
-       "[K10 Morphism (degree 2): K5 -> K5]"
+       "\n",
+       "----------------------------------------------------------------------{CMBN 1}\n",
+       "<1 * 10>\n",
+       "<2 * 11>\n",
+       "<3 * 12>\n",
+       "<4 * 13>\n",
+       "------------------------------------------------------------------------------\n"
       ]
      },
      "execution_count": 70,
@@ -1954,7 +1967,7 @@
     }
    ],
    "source": [
-    "(cat:def upper-shift2 (cat:cmps upper-shift upper-shift))"
+    "(cat:? identity? comb1)"
    ]
   },
   {
@@ -1967,7 +1980,9 @@
     {
      "data": {
       "text/plain": [
-       "2"
+       "\n",
+       "----------------------------------------------------------------------{CMBN 1}\n",
+       "------------------------------------------------------------------------------\n"
       ]
      },
      "execution_count": 71,
@@ -1975,13 +1990,57 @@
      "output_type": "execute_result"
     }
    ],
+   "source": [
+    "(cat:2cmbn-sbtr (cat:cmpr ccn) comb1 (cat:? identity? comb1))"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 72,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "[K10 Morphism (degree 2): K5 -> K5]"
+      ]
+     },
+     "execution_count": 72,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "(cat:def upper-shift2 (cat:cmps upper-shift upper-shift))"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 73,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "2"
+      ]
+     },
+     "execution_count": 73,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
    "source": [
     "(cat:degr upper-shift2)"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 72,
+   "execution_count": 74,
    "metadata": {
     "collapsed": false
    },
@@ -1998,7 +2057,7 @@
        "------------------------------------------------------------------------------\n"
       ]
      },
-     "execution_count": 72,
+     "execution_count": 74,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -2009,7 +2068,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 73,
+   "execution_count": 75,
    "metadata": {
     "collapsed": false
    },
@@ -2020,7 +2079,7 @@
        "[K11 Morphism (degree 1): K5 -> K5]"
       ]
      },
-     "execution_count": 73,
+     "execution_count": 75,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -2031,7 +2090,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 74,
+   "execution_count": 76,
    "metadata": {
     "collapsed": false
    },
@@ -2042,7 +2101,7 @@
        "1"
       ]
      },
-     "execution_count": 74,
+     "execution_count": 76,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -2053,7 +2112,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 75,
+   "execution_count": 77,
    "metadata": {
     "collapsed": false
    },
@@ -2070,57 +2129,13 @@
        "------------------------------------------------------------------------------\n"
       ]
      },
-     "execution_count": 75,
-     "metadata": {},
-     "output_type": "execute_result"
-    }
-   ],
-   "source": [
-    "(cat:? twice-up-shift comb1)"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 76,
-   "metadata": {
-    "collapsed": false
-   },
-   "outputs": [
-    {
-     "data": {
-      "text/plain": [
-       "[K12 Morphism (degree 0): K5 -> K5]"
-      ]
-     },
-     "execution_count": 76,
-     "metadata": {},
-     "output_type": "execute_result"
-    }
-   ],
-   "source": [
-    "(cat:def up-d (cat:cmps upper-shift (cat:dffr1 ccn)))"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 77,
-   "metadata": {
-    "collapsed": false
-   },
-   "outputs": [
-    {
-     "data": {
-      "text/plain": [
-       "[K13 Morphism (degree 0): K5 -> K5]"
-      ]
-     },
      "execution_count": 77,
      "metadata": {},
      "output_type": "execute_result"
     }
    ],
    "source": [
-    "(cat:def d-up (cat:cmps (cat:dffr1 ccn) upper-shift))"
+    "(cat:? twice-up-shift comb1)"
    ]
   },
   {
@@ -2133,10 +2148,7 @@
     {
      "data": {
       "text/plain": [
-       "\n",
-       "----------------------------------------------------------------------{CMBN 1}\n",
-       "<1 * 11>\n",
-       "------------------------------------------------------------------------------\n"
+       "[K12 Morphism (degree 0): K5 -> K5]"
       ]
      },
      "execution_count": 78,
@@ -2145,7 +2157,7 @@
     }
    ],
    "source": [
-    "(cat:? up-d 1 11)"
+    "(cat:def up-d (cat:cmps upper-shift (cat:dffr1 ccn)))"
    ]
   },
   {
@@ -2158,9 +2170,7 @@
     {
      "data": {
       "text/plain": [
-       "\n",
-       "----------------------------------------------------------------------{CMBN 1}\n",
-       "------------------------------------------------------------------------------\n"
+       "[K13 Morphism (degree 0): K5 -> K5]"
       ]
      },
      "execution_count": 79,
@@ -2169,7 +2179,7 @@
     }
    ],
    "source": [
-    "(cat:? d-up 1 11)"
+    "(cat:def d-up (cat:cmps (cat:dffr1 ccn) upper-shift))"
    ]
   },
   {
@@ -2184,12 +2194,7 @@
       "text/plain": [
        "\n",
        "----------------------------------------------------------------------{CMBN 1}\n",
-       "<1 * 10>\n",
-       "<2 * 11>\n",
-       "<3 * 12>\n",
-       "<4 * 13>\n",
-       "<5 * 14>\n",
-       "<6 * 15>\n",
+       "<1 * 11>\n",
        "------------------------------------------------------------------------------\n"
       ]
      },
@@ -2199,7 +2204,7 @@
     }
    ],
    "source": [
-    "(cat:def comb3 (cat:cmbn 1 1 10 2 11 3 12 4 13 5 14 6 15))"
+    "(cat:? up-d 1 11)"
    ]
   },
   {
@@ -2214,9 +2219,6 @@
       "text/plain": [
        "\n",
        "----------------------------------------------------------------------{CMBN 1}\n",
-       "<2 * 11>\n",
-       "<4 * 13>\n",
-       "<6 * 15>\n",
        "------------------------------------------------------------------------------\n"
       ]
      },
@@ -2226,7 +2228,7 @@
     }
    ],
    "source": [
-    "(cat:? up-d comb3)"
+    "(cat:? d-up 1 11)"
    ]
   },
   {
@@ -2235,6 +2237,63 @@
    "metadata": {
     "collapsed": false
    },
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "\n",
+       "----------------------------------------------------------------------{CMBN 1}\n",
+       "<1 * 10>\n",
+       "<2 * 11>\n",
+       "<3 * 12>\n",
+       "<4 * 13>\n",
+       "<5 * 14>\n",
+       "<6 * 15>\n",
+       "------------------------------------------------------------------------------\n"
+      ]
+     },
+     "execution_count": 82,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "(cat:def comb3 (cat:cmbn 1 1 10 2 11 3 12 4 13 5 14 6 15))"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 83,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "\n",
+       "----------------------------------------------------------------------{CMBN 1}\n",
+       "<2 * 11>\n",
+       "<4 * 13>\n",
+       "<6 * 15>\n",
+       "------------------------------------------------------------------------------\n"
+      ]
+     },
+     "execution_count": 83,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "(cat:? up-d comb3)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 84,
+   "metadata": {
+    "collapsed": false
+   },
    "outputs": [
     {
      "data": {
@@ -2247,7 +2306,7 @@
        "------------------------------------------------------------------------------\n"
       ]
      },
-     "execution_count": 82,
+     "execution_count": 84,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -2265,7 +2324,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 83,
+   "execution_count": 85,
    "metadata": {
     "collapsed": false
    },
@@ -2276,7 +2335,7 @@
        "[K1 Chain-Complex]"
       ]
      },
-     "execution_count": 83,
+     "execution_count": 85,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -2287,7 +2346,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 84,
+   "execution_count": 86,
    "metadata": {
     "collapsed": false
    },
@@ -2308,7 +2367,7 @@
        "NIL"
       ]
      },
-     "execution_count": 84,
+     "execution_count": 86,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -2319,7 +2378,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 85,
+   "execution_count": 87,
    "metadata": {
     "collapsed": false
    },
@@ -2330,7 +2389,7 @@
        "[K3 Cohomology-Class on K1 of degree 1]"
       ]
      },
-     "execution_count": 85,
+     "execution_count": 87,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -2341,7 +2400,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 86,
+   "execution_count": 88,
    "metadata": {
     "collapsed": false
    },
@@ -2362,7 +2421,7 @@
        "NIL"
       ]
      },
-     "execution_count": 86,
+     "execution_count": 88,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -2373,7 +2432,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 87,
+   "execution_count": 89,
    "metadata": {
     "collapsed": false
    },
@@ -2394,7 +2453,7 @@
        "NIL"
       ]
      },
-     "execution_count": 87,
+     "execution_count": 89,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -2405,7 +2464,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 88,
+   "execution_count": 90,
    "metadata": {
     "collapsed": false
    },
@@ -2426,7 +2485,7 @@
        "NIL"
       ]
      },
-     "execution_count": 88,
+     "execution_count": 90,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -2437,7 +2496,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 89,
+   "execution_count": 91,
    "metadata": {
     "collapsed": false
    },
@@ -2458,7 +2517,7 @@
        "NIL"
       ]
      },
-     "execution_count": 89,
+     "execution_count": 91,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -2469,7 +2528,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 90,
+   "execution_count": 92,
    "metadata": {
     "collapsed": false
    },
@@ -2498,7 +2557,7 @@
        "(9 8 7)"
       ]
      },
-     "execution_count": 90,
+     "execution_count": 92,
      "metadata": {},
      "output_type": "execute_result"
     }
diff --git a/src/macros.lisp b/src/macros.lisp
index 5980920..0fefbb2 100644
--- a/src/macros.lisp
+++ b/src/macros.lisp
@@ -76,6 +76,11 @@ and returns VALUE.
 
 
 (DEFMACRO CFFC (term)
+  "-----------------------------------------------------------------[macro-doc]
+CFFC
+Args: (term)
+Returns the the coefficient (integer) of a term.
+------------------------------------------------------------------------------"
   `(car ,term))
 
 
@@ -84,6 +89,11 @@ and returns VALUE.
 
 
 (DEFMACRO GNRT (term)
+  "-----------------------------------------------------------------[macro-doc]
+GNRT
+Args: (term)
+Returns the the generator of a term.
+------------------------------------------------------------------------------"
   `(cdr ,term))