A few notes regarding Zope Book, mainly addressed to people at Zope Corporation: I wish the Zope Book API reference contained much more examples than it does today. I understand that from a purely definition perspective the examples should not be neccessary if the definition is correct. However, real people feel much more comfortable seeing real usage of defined commands and funtions. Examples make them feel more at ease with the API, and consequently prevent frequent questions in the mailing list. I think that every and each function should list two examples. Look at it: A function like DateTime.dow() is so simple that any example may seem unneccesary. But it is ridiculously easy to write the example, so why not do it? And while you are at it, you could add some advanced example showing an unusual usage of the function. A function ZCatalog.getobject() is more complicated. There is a short definition in the API reference, but there is no information describing what is the purpose of REQUEST variable as an optional parameter of getobject. I have no idea what will happen if I put a REQUEST as a getobject parameter. If there was a single sentence telling me about it, that would be great. But if there was an example of usage, an example with bogus values like "Elvis", that would be nirvana. By the way, all example values featuring "foo" and "bar" should be IMHO changed to something like "Elvis". I know that "foo/bar" pair is very popular, but IMHO it is rather confusing to newcomers. Furthermore, we still have at least one completely undocumented function that is absolutely essential to ZCatalog chapter in Zope Book. It is reindex_object. Automatic cataloging does not work without calling reindex_object during ZClass instance creation, yet it is never mentioned in the ZCatalog chapter, and it is not described in the API reference. There are other undocumented functions and options (such as sort_expr option of dtml-in), but I take it these are going to be documented when Zope Corporation deems them stable (that is both non-crashing and fitting the API philosophy), and they are often nonessential. -- Milos Prudek