Congratulations on getting the book to this stage!!
It is very readable and I hope it is well promoted, and well received.
One obvious presentation improvement I suggest is that you make ALL zope
code references in the same typographic style.
For example throughout most of the text you sensibly have DTML and Python
examples in courier or equivalent.
But in the Appendices, for example
http://www.zope.org/Members/michel/ZB/AppendixA.html under sections marked
'Attributes', there is not a clear consistent distinction:
MIME Content-Transfer-Encoding header, defaults to base64. Valid encoding
options include base64, quoted-printable, uuencode, x-uuencode, uue, x-uue,
and 7bit. If the encode attribute is set to 7bit no encoding is done on the
block and the data is assumed to be in a valid MIME format.
"encode=string" should display in courier also like all examples.
And if possible put one extra line space after each Attribute description
before the next entry. Thought this takes up a little more space, it is
white space well used adn really helps one to find and absorb this crucial
An editorial suggestion I would make is that in the Appendices, MORE
examples would be BETTER and clearer definitions and examples of the
attributes arguments would really help too. Even a single one or two-line
example after each 'Attributes section would be a godsend. I imagine there
are lots of juicy examples in the archives.
For example check sendmail,
Also there is no mention about the sendmail quirkiness of formatting,
needing space after the subject: line
This is a FAQ and surely belongs in the appendix of the only Zope book.
Are there others?
In general for the Appendices, please check that explicitly it is clear and
consistent when and if anything is returned, and when and how arguments are
You all know, and take all this for granted no doubt, but others truly
The API aspect is one that holds so many people back and so many questions
about real-world use. Copious well placed examples go a long way.
I know how hard it is use to make a book and how many endless fiddly
time-consuming tasks there are. But it really is worth getting this right. I
work for 10 years in the design and production side of book publishing.
Ditto the index.
I hope you push to make sure your editorial team at OReilly are really
behind you on helping to produce a great index and will sweat all the
details and typographic minutiae which do matter so much when you hold the
A classic example is 'Lingo in a Nutshell' [ORA] which has very detailed
examples and excellent tables and appendices, but was marred by a cheap fast
shallow index. It was author Bruce Epstein's painful learning curve. It is
still the definitive LINGO book, but widely criticized for lack of serious
index. Bruce later added stuff online and vowed to fix it in the next
edition. As I recall from his post to the Direct-L mailing list, he said
that he had not been personally very involved in the index, and as an
exhausted and tired new author, he had not reckoned on what could go wrong,
nor how important the index is to a static printed paper book. Very
different from the dynamic online world where a few searches on google or
wherever will get a handy reference, backed up by a post to
Jason CUNLIFFE = NOMADICS['Interactive Art and Technology'].DesignDirector
Zope maillist - [EMAIL PROTECTED]
** No cross posts or HTML encoding! **
(Related lists -