The first and best free ZoPe book, written by it's programmers. An essential resource for would-be zope developers.
Zope book mirror
The zwiki-based Zope Book Mirror has moved to ZopeWiki:ZopeBook . Here is some old discussion about it.
Prompted by some discussion on #zope (see Motivation below), this is an experiment to answer some questions:
- is Zwiki capable of storing the Zope Book , and if not why not ?
- is this a way to get a more usable version of the book ?
- could this be a way to give the book a more agile edit process ?
Since DTML is enabled throughout this wiki, and the zope book contains
lots of DTML examples (not all quoted) that we don't want to execute, I
had to set the
no_dtml property on some of these pages in the ZMI. This
flag now disables DTML parsing (cook()) as well as execution, and can be
Attempting to save chapter 3 I hit the regexp max recursion error. This turned out to be the dumb HTML-tag-stripping regexp. After disabling this I was able to save all chapters without trouble.
How close is Zwiki's rendering to the Zope Book seen on zope.org ? Compare the two.
- skin differences of course - no inline comments by default, no sidebar, no big table, faster, no horizontal scrolling problem .
- no plone stylesheet, affecting things like font size, blue highlights, and bolding of definition list items (?). Easily fixed if needed.
- Here ,
in the sentence beginning "Sort the sequence seq of
objects...", zope.org puts each quoted word on a separate line. If this a skin difference, our behaviour seems better.
- Zwiki is doing wiki linking. This is arguably great in some cases: DateTime?, DTMLDocuments?, DTMLMethod. Not so great in others: DTMLs?, [name=value]? .
- STX hyperlinks containing ' (single quote) are not rendered correctly. Looks like a difference in structured text version.
- I mirrored the images too (using ftp to bulk-upload them) but it seems STX image links don't work in Zwiki right now.
Otherwise things look pretty good! As they should, since the Zope Book is written in nice portable StructuredText.
We should not expend much effort on edits without thinking about a syncing process, but to see how it worked I went ahead and fixed the small problem that started all this: I linked some standard module references near the top of Appendix A to the module docs in Appendix B.
This was not so easy to accomplish gracefully with STX. I had to add HTML named anchors in Appendix B. In Appendix A I had to convert the references to structured text links and remove the single quotes around the module names; also reference the wiki page id of Appendix B. I wished for the automatic heading anchors and richer linking of RestructuredText.
I did the same in appendices A and C.
A table of contents at the top of these pages would be quite helpful. STX doesn't do this (RestructuredText does) but it be could done by hand, by DTML (like FAQ) or by python code. I added a quick one to the DTML reference.
PurpleNumbers, anyone ?
Why ? Well, first to test zwiki's fitness, second to get more usable docs now, and third to explore ways to bring more agility into the zope docs maintenance process. Why ? Here's the chat in which I expound on this a bit. (Thanks BradB, MacPizza & others):
MacPizza: sequence.sort( sm: cool, dtml has that MacPizza: has what? sm: has _.sequence.sort MacPizza: sure MacPizza: as documented sm: jesus.. if only I could bookmark the zope book with fricking comments off ***sm grovels around in murky docs sm: or if they fit in my browser window sm: darnit.. you should all go and +1 http://collector.zope.org/ZopeOrg/106 sm: so just where is sequence documented ? am I being dumb ? sure I could google it.. BradB: sm: In the Zope API docs sm: searching the dtml & tal reference appendices finds "see sequence", no link sm: it's not in the python 2.1 and 2.2 library module index BradB: eh, in the Zope API docs MacPizza: appendix b sm: ah, thank you sm: the zope book is excellent as far as it goes, but it needs more agile updating now BradB: sm: Reading the source of example products is even better. BradB: And quicker sm: so it seems.. still.. isn't that quite sad ? BradB: sm: No. Documentation is evil. mphardy_: python is meant to be read sm: that's foolish.. good documentation adds value BradB: In some cases it's much harder to learn without docs, but in all cases the code is always the more authoritative reference. mphardy_: sm: are you volunteering? sm: of course.. if it were possible I would fix this now BradB: sm: Good documentation adds expenses BradB: Because when it goes out of date, it's /worse/ than no documentatoin BradB: *documentation sm: but there is no agile update process, hence the docs remain not terribly good mphardy_: source never goes out of date sm: and will remain so forever sm: zope corp do you get this ? I wish I could help BradB: A combonation of following the mailing lists and reading the source are more interesting than reading useless documentation that only describes the most basic steps in how to do things. BradB: *combination BradB: sm: You can volunteer to maintain the ZB sm: but I don't have time to dick around with their non-agile process sm: I have the energy and will to fix this issue now, but it's being squandered sm: this is happening a hundred times a day sm: that's all I'm saying BradB: sm: Just remember: It's All Bullshit. sm: ack! BradB: Just volunteer to maintain it BradB: Then you will agile-enable yourself sm: I am digging out the stx from sourceforge right now ***sm won't be signing draconian contributor agreements though BradB: The contributor agreement is what happens when you have more than a few employees on your payroll, and the state and quality of your CVS in large part affects your ability to keep paying them. sm: fine.. but doesn't quality of the docs impact employees ? sm: we can do better, IMHO BradB: sm: No. If it did they'd be better docs. BradB: It's the way Open Source works. Implementation arises from need (or insanity, take your pick). sm: it does impact them, whether they realize it or not BradB: Perhaps not directly and immediately enough sm: zope 2 & 3 development has become much more agile & open sm: the website and docs will also become more agile.. eventually.. and quality will go up, and zope and zope corp will have even greater success sm: or they won't sm: and community energy that could have been tapped has been lost sm: which is fine, but I'd love to see zope take the swift optimal path to glory, and I'd love to waste less energy when I work with zope BradB: sm: You're not wasting energy reading source. You're learning the software better than you possibly could any other way. sm: BradB: been there, done that, now I'm just trying to look up reference information for the nth time
What's wrong with that one at the end of appendix B ?
It includes an embedded STX
code apostrophes (is there special code there to mask out wikilinks?)