The first and best free ZoPe book, written by it's programmers. An essential resource for would-be zope developers.

RemoteWikiURL: http://zopewiki.org/

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:

Results, issues

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 used per-page.

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.

Otherwise things look pretty good! As they should, since the Zope Book is written in nice portable StructuredText.

Edits

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.

Ideas

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 ?

Motivation

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



comments:

neat! --DeanGoodmanson, Thu, 14 Aug 2003 22:18:43 +0000 reply

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?)

"and example here":http://zwiki.org

this is great --SimonMichael, Sun, 05 Oct 2003 17:38:15 -0700 reply
except it's the 2.5.1 zope book, which sucks. When the latest is available in source form I'd like to redo these pages.