Index: waeup/branches/ulif-rewrite/src/waeup/university/certificate.txt
===================================================================
--- waeup/branches/ulif-rewrite/src/waeup/university/certificate.txt	(revision 4331)
+++ waeup/branches/ulif-rewrite/src/waeup/university/certificate.txt	(revision 4332)
@@ -230,4 +230,28 @@
      <waeup.university.certificate.Certificate object at 0x...>
 
+Event Subscribers
+=================
+
+.. function:: removedCourseHandler(course, event)
+
+   An event subscriber triggered for
+   :class:`grok.IObjectRemovedEvent`s, when an :class:`ICourse`
+   instance is removed from a container.
+
+   Tries to remove all referencing :class:`CertificateCourse`
+   instances that reference the removed course.
+
+   To accomplish that, the parents of the removed course are looked up
+   for a certifcate container which contains a certificate-course that
+   contains a reference to the deleted course.
+
+   .. seealso:: :ref:`removecertificatecourses`
+
+   **handles:**
+     :class:`ICourse`
+
+   **event type:**
+     :class:`grok.IObjectRemovedEvent`
+
 Examples
 ========
@@ -268,2 +292,113 @@
     True
 
+Also instances of :class:`CertificateCourse` can be created by asking
+the component architechture:
+
+    >>> from zope.component import createObject
+    >>> mycertcourse = createObject(u'waeup.CertificateCourse')
+    >>> mycertcourse
+    <waeup.university.certificate.CertificateCourse object at 0x...>
+
+.. _removecertificatecourses:
+
+Persistence of certificate courses
+----------------------------------
+
+If a certificate course requires a certain course and this is course
+is deleted, also the referencing certificate course is deleted.
+
+We setup a data structure that reflects typical usage. It looks like
+this::
+
+    Department-Instance
+    |
+    +---> courses
+    |        |
+    |        +--------------------> Course-Instance
+    |                                        ^
+    +---> certificates                       |
+             |                               |
+             +-----> Certificate-Instance    |
+                        |                    |
+                        +------> Certificate-Course
+
+The certifcate-Course here refers to a Course-Instance.
+
+In Python we build such a structure like this (from top to bottom):
+
+    >>> from zope.component import createObject
+    >>> mydept = createObject('waeup.Department')
+
+In real world use this data will be stored in a ZODB. We setup our own
+litte ZODB backend (which is easy!):
+
+    >>> from ZODB import FileStorage, DB
+    >>> dbpath = 'tinyData.fs'
+    >>> class TinyZODB(object):
+    ...   def __init__(self, path=dbpath):
+    ...     self.storage = FileStorage.FileStorage(path)
+    ...     self.db = DB(self.storage)
+    ...     self.connection = self.db.open()
+    ...     self.dbroot = self.connection.root()
+    ...   def close(self):
+    ...     self.connection.close()
+    ...     self.db.close()
+    ...     self.storage.close()
+
+Now we can use this ZODB as backend database and store our data
+structure:
+
+    >>> import transaction
+    >>> db = TinyZODB()
+    >>> dbroot = db.dbroot
+    >>> dbroot['mydept'] = mydept
+    >>> mycourse = createObject('waeup.Course')
+    >>> mycourse.code = 'MYCOURSE'
+    >>> mydept.courses.addCourse(mycourse)
+    >>> mycert = createObject('waeup.Certificate')
+    >>> mycert.code = 'MYCERT'
+    >>> mydept.certificates.addCertificate(mycert)
+    >>> mycert.addCourseRef(mycourse)
+
+    >>> transaction.commit()
+
+The data is now stored in the ZODB. We can close the DB, reopen it
+later and the data will still be there:
+
+    >>> db.close()
+    >>> newdb = TinyZODB()
+    >>> newdbroot = newdb.dbroot
+    >>> list(newdbroot)
+    ['mydept']
+
+The certificate-course we stored in the certificate is indeed a
+reference to the course, not a copy of it:
+
+    >>> course = newdbroot['mydept'].courses['MYCOURSE']
+    >>> certcourse = newdbroot['mydept'].certificates['MYCERT']['MYCOURSE']
+    >>> certcourse.course is course
+    True
+
+So, we can be sure that modifications to the course are immediately
+reflected in the certcourse.
+
+The interesting question now is: what happens to ``mycertcourse`` when
+the referenced course ``mycourse`` is deleted?
+
+Let's have a look:
+
+    >>> list(newdbroot['mydept'].certificates['MYCERT'].keys())
+    [u'MYCOURSE']
+
+    >>> del newdbroot['mydept'].courses['MYCOURSE']
+    >>> newdbroot['mydept']._p_changed = True
+    >>> transaction.commit()
+    >>> list(newdbroot['mydept'].certificates['MYCERT'].keys())
+    []
+
+As we can see, the course was also removed from the certificate.
+
+Clean up:
+
+    >>> import os
+    >>> os.unlink(dbpath)
