[Zope] Add more examples in Zope Book API reference

[Milos Prudek]

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