Zope Book call for assistance
Hi, Time has rolled around for me to ask for assistance with editing the most recent edition of the Zope Book. A "2.6 edition" of the Zope Book exists at http://www.zope.org/Documentation/Books/ZopeBook/2_6Edition/index_html. It has many new chapters and a most existing chapters have been rewritten and extended. But it's not finished and I'd really like this Zope Book edition to be the "current" edition by the time Zope 2.6.1 comes out. If anyone has the time and inclination to edit and extend one of the following chapters of the 2.6 edition Zope Book, you will be rewarded with a glowing mention in the Preface of the book. If you professionally edit two chapters, you'll be considered a coauthor and your name will go on the header. That'd be nice on a resume, I'd imagine. Maintaining Zope: <http://www.zope.org/Documentation/Books/ZopeBook/2_6Edition/MaintainingZope.... > Extending Zope (ZClasses): < http://www.zope.org/Documentation/Books/ZopeBook/2_6Edition/CustomZopeObject... > Relational Database Connectivity: < http://www.zope.org/Documentation/Books/ZopeBook/2_6Edition/RelationalDataba... > Users and Security: < http://www.zope.org/Documentation/Books/ZopeBook/2_6Edition/Security.stx
Advanced DTML: < http://www.zope.org/Documentation/Books/ZopeBook/2_6Edition/AdvDTML.stx
Searching and Categorizing Content (ZCatalog): < http://www.zope.org/Documentation/Books/ZopeBook/2_6Edition/SearchingZCatalo... > Advanced Zope Scripting: < http://www.zope.org/Documentation/Books/ZopeBook/2_6Edition/ScriptingZope.st... > "Editing and extending" these chapters means: - Downloading the source version of the chapter via the "STX source" link at the top of the page. - Addressing all the comments in the section (by deleting the extraneous ones and answering via narrative in the document the meaningful ones). - Extending the chapter based on your own personal experience. - Optionally re-screenshotting and renumbering the figures based on the format of the already re-screenshotted Basic Objects chapter (I can do this as well if you can't, as long as I know what needs to be done). - Sending the edited source back to me for inclusion into the Book. Thanks much! - C
Hi, --On Donnerstag, 5. Dezember 2002 23:20 -0500 Chris McDonough <chrism@zope.com> wrote: ...
Advanced DTML: < http://www.zope.org/Documentation/Books/ZopeBook/2_6Edition/AdvDTML.stx
erm... would "advanced DTML" not be the short sentence: "avoid DTML where you can"? ;) Btw. did you think of putting the whole DTML stuff at the end for reference only to help migrating old products and turn the whole thing a bit around so beginners get a clear path of Zope development? I found it a bit confusing when I edited the german translation of the 2.3 book a year ago. Regards Tino
erm... would "advanced DTML" not be the short sentence: "avoid DTML where you can"? ;)
That'd be ok, except that DTML can of course do things that ZPT can't, yada yada yada.
Btw. did you think of putting the whole DTML stuff at the end for reference only to help migrating old products and turn the whole thing a bit around so beginners get a clear path of Zope development? I found it a bit confusing when I edited the german translation of the 2.3 book a year ago.
That's probably a good idea. But I think the rewritten chapters explain when to use ZPT and when to use DTML. And DTML still needs to be given some attention for the reason I say above... - C
DTML needs to be given the same amount of attention as it always has. For some bizarre reason, DTML makes sense in my head....even complicated logic... "Doctor! Do I need help?" It's one of the reasons I really liked Zope three years ago when starting with it.... The tag structure just made sense and was similar to a tool I used to get database calls and logic on a web page... "Long live DTML!!" ----- Original Message ----- From: "Chris McDonough" <chrism@zope.com> To: "Tino Wildenhain" <tino@wildenhain.de> Cc: <zope-dev@zope.org>; <zope@zope.org> Sent: Friday, December 06, 2002 9:50 AM Subject: Re: [Zope] Re: [Zope-dev] Zope Book call for assistance
erm... would "advanced DTML" not be the short sentence: "avoid DTML where you can"? ;)
That'd be ok, except that DTML can of course do things that ZPT can't, yada yada yada.
Btw. did you think of putting the whole DTML stuff at the end for reference only to help migrating old products and turn the whole thing a bit around so beginners get a clear path of Zope development? I found it a bit confusing when I edited the german translation of the 2.3 book a year ago.
That's probably a good idea. But I think the rewritten chapters explain when to use ZPT and when to use DTML. And DTML still needs to be given some attention for the reason I say above...
- C
_______________________________________________ Zope maillist - Zope@zope.org http://lists.zope.org/mailman/listinfo/zope ** No cross posts or HTML encoding! ** (Related lists - http://lists.zope.org/mailman/listinfo/zope-announce http://lists.zope.org/mailman/listinfo/zope-dev )
Quick question... What stx engine is used to process the Zope book? It's a customized version, right? Is there anywhere that book volunteers (such as myself) can get the stx engine? I want to see how my edits are going to render, and make sure I haven't borked the structured text. --PW Paul Winkler http://www.slinkp.com "Welcome to Muppet Labs, where the future is made - today!"
Hi Paul, The easiest way is probably to create a BackTalk book/document in your member are on Zope.org... then cut and paste into it. Or install BackTalk on one of your own systems (http://backtalk.sourceforge.net). On Thu, 2002-12-19 at 03:56, Paul Winkler wrote:
Quick question... What stx engine is used to process the Zope book? It's a customized version, right?
Is there anywhere that book volunteers (such as myself) can get the stx engine? I want to see how my edits are going to render, and make sure I haven't borked the structured text.
--PW
Paul Winkler http://www.slinkp.com "Welcome to Muppet Labs, where the future is made - today!"
_______________________________________________ Zope maillist - Zope@zope.org http://lists.zope.org/mailman/listinfo/zope ** No cross posts or HTML encoding! ** (Related lists - http://lists.zope.org/mailman/listinfo/zope-announce http://lists.zope.org/mailman/listinfo/zope-dev )
On Thu, Dec 19, 2002 at 11:08:42AM -0500, Chris McDonough wrote:
Hi Paul,
The easiest way is probably to create a BackTalk book/document in your member are on Zope.org... then cut and paste into it. Or install BackTalk on one of your own systems (http://backtalk.sourceforge.net).
ah, thanks, that's exactly what i needed. Now I can document 2.6.1 *in* 2.6.1 (cvs). :) --PW -- Paul Winkler http://www.slinkp.com "Welcome to Muppet Labs, where the future is made - today!" Look! Up in the sky! It's MILDLY- INVADER! (courtesy of isometric.spaceninja.com)
On 19 Dec 2002, Chris McDonough wrote:
The easiest way is probably to create a BackTalk book/document in your member are on Zope.org... then cut and paste into it. Or install BackTalk on one of your own systems (http://backtalk.sourceforge.net). On the other hand I would really love if the stx engine would be available as separate module. This would brgeat help in other projects than backtalk and could attract developers who are not especially interested in backtalk development.
Kind regards Andreas.
The StructuredText package in Zope has no dependencies on any other Zope modules AFAIK, so it'd probably be fine to make a standalone distribution. - C ----- Original Message ----- From: "Andreas Tille" <tillea@rki.de> To: "Zope user list" <zope@zope.org> Sent: Friday, December 20, 2002 2:25 AM Subject: [Zope] Re: Zope Book call for assistance
On 19 Dec 2002, Chris McDonough wrote:
The easiest way is probably to create a BackTalk book/document in your member are on Zope.org... then cut and paste into it. Or install BackTalk on one of your own systems (http://backtalk.sourceforge.net). On the other hand I would really love if the stx engine would be available as separate module. This would brgeat help in other projects than backtalk and could attract developers who are not especially interested in backtalk development.
Kind regards
Andreas.
_______________________________________________ Zope maillist - Zope@zope.org http://lists.zope.org/mailman/listinfo/zope ** No cross posts or HTML encoding! ** (Related lists - http://lists.zope.org/mailman/listinfo/zope-announce http://lists.zope.org/mailman/listinfo/zope-dev )
On Fri, 20 Dec 2002, Chris McDonough wrote:
The StructuredText package in Zope has no dependencies on any other Zope modules AFAIK, so it'd probably be fine to make a standalone distribution. This would be great. It would be even greater if this would be not a standalone Zope package but a standalone Python module for use in normal Python programs without Zope.
Kind regards Andreas.
As Chris wrote, STX can be used standalone independent of Zope in any other Python program. But if you have the choice better take reST from the docutils package. -aj --On Freitag, 20. Dezember 2002 09:04 +0100 Andreas Tille <tillea@rki.de> wrote:
On Fri, 20 Dec 2002, Chris McDonough wrote:
The StructuredText package in Zope has no dependencies on any other Zope modules AFAIK, so it'd probably be fine to make a standalone distribution. This would be great. It would be even greater if this would be not a standalone Zope package but a standalone Python module for use in normal Python programs without Zope.
Kind regards
Andreas.
_______________________________________________ Zope maillist - Zope@zope.org http://lists.zope.org/mailman/listinfo/zope ** No cross posts or HTML encoding! ** (Related lists - http://lists.zope.org/mailman/listinfo/zope-announce http://lists.zope.org/mailman/listinfo/zope-dev )
--------------------------------------------------------------------- - Andreas Jung http://www.andreas-jung.com - - EMail: andreas at andreas-jung.com - - "Life is too short to (re)write parsers" - ---------------------------------------------------------------------
On Fri, 20 Dec 2002, Andreas Jung wrote:
As Chris wrote, STX can be used standalone independent of Zope in any other Python program. But if you have the choice better take reST from the docutils package. Thanks for the Hint. Back to the topic: It would be nice if someone could write a reST script which could convert zope-book.stx to different formats.
Kind regards Andreas.
Hi Chris, --On Freitag, 6. Dezember 2002 09:50 -0500 Chris McDonough <chrism@zope.com> wrote:
erm... would "advanced DTML" not be the short sentence: "avoid DTML where you can"? ;)
That'd be ok, except that DTML can of course do things that ZPT can't, yada yada yada.
These are exactly the things you shouldn't neither do in DTML nor in ZPT :-) I'd start the lessons with ZPT to only show static content and may be macros. Then the logical order would be introduction to python scripts without HTML output - only show how they are used to calculate and output simple values, lists, dictionaries and so on. Next chapter should show how one uses the scripts with ZPT to provide output into HTML. Then the usual things like Catalog, ZSQL, important API parts, etc. Don't you think this would be clearer for the beginner? Regards Tino
Btw. did you think of putting the whole DTML stuff at the end for reference only to help migrating old products and turn the whole thing a bit around so beginners get a clear path of Zope development? I found it a bit confusing when I edited the german translation of the 2.3 book a year ago.
That's probably a good idea. But I think the rewritten chapters explain when to use ZPT and when to use DTML. And DTML still needs to be given some attention for the reason I say above...
- C
On Fri, 2002-12-06 at 19:13, Tino Wildenhain wrote:
These are exactly the things you shouldn't neither do in DTML nor in ZPT :-)
What do you suggest people use for a templating language for email, JavaScript, SQL, etc? I think it's too much to expect them to use Python to do this (esp. wrt SQL methods).
I'd start the lessons with ZPT to only show static content and may be macros. Then the logical order would be introduction to python scripts without HTML output - only show how they are used to calculate and output simple values, lists, dictionaries and so on. Next chapter should show how one uses the scripts with ZPT to provide output into HTML. Then the usual things like Catalog, ZSQL, important API parts, etc.
Don't you think this would be clearer for the beginner?
Sure. I'd love to rewrite the entirety of the Zope Book. But please notice that I'm asking for help finishing the existing chapters, so I don't think this is a realistic goal. - C
Hi Chris, --On Freitag, 6. Dezember 2002 21:27 -0500 Chris McDonough <chrism@zope.com> wrote:
On Fri, 2002-12-06 at 19:13, Tino Wildenhain wrote:
These are exactly the things you shouldn't neither do in DTML nor in ZPT :-)
What do you suggest people use for a templating language for email, JavaScript, SQL, etc? I think it's too much to expect them to use Python to do this (esp. wrt SQL methods).
Oh, is it? I'd rather like to write %(name)s %(value)d then <dtml-whatever value> Recently I read the python-dbi spec and its very nice to see what you could do with the above form. There are even standard ways to do multiple querys or function calls. (Hope I can contribute a product for this as time permits) For E-Mail and Javascript templates I also find it less confusing if I can use %(var)s form. As a general solution for texts one can use "file" which has an edit tab for several releases of zope now. Then use it like this: context.thefile.read() % context.REQUEST.form or whatever seems appropriate to get values from. E-Mail even gets clearer with the solution since you can easyly loop and do whatever instead of multiple <dtml-sendmail> tags. Regards Tino
I'd start the lessons with ZPT to only show static content and may be macros. Then the logical order would be introduction to python scripts without HTML output - only show how they are used to calculate and output simple values, lists, dictionaries and so on. Next chapter should show how one uses the scripts with ZPT to provide output into HTML. Then the usual things like Catalog, ZSQL, important API parts, etc.
Don't you think this would be clearer for the beginner?
Sure. I'd love to rewrite the entirety of the Zope Book. But please notice that I'm asking for help finishing the existing chapters, so I don't think this is a realistic goal.
- C
On Sat, 2002-12-07 at 06:11, Tino Wildenhain wrote:
Hi Chris,
--On Freitag, 6. Dezember 2002 21:27 -0500 Chris McDonough <chrism@zope.com> wrote:
On Fri, 2002-12-06 at 19:13, Tino Wildenhain wrote:
These are exactly the things you shouldn't neither do in DTML nor in ZPT :-)
What do you suggest people use for a templating language for email, JavaScript, SQL, etc? I think it's too much to expect them to use Python to do this (esp. wrt SQL methods).
Oh, is it? I'd rather like to write %(name)s %(value)d then <dtml-whatever value> Recently I read the python-dbi spec and its very nice to see what you could do with the above form. There are even standard ways to do multiple querys or function calls. (Hope I can contribute a product for this as time permits)
For E-Mail and Javascript templates I also find it less confusing if I can use %(var)s form.
As a general solution for texts one can use "file" which has an edit tab for several releases of zope now. Then use it like this:
context.thefile.read() % context.REQUEST.form
or whatever seems appropriate to get values from.
E-Mail even gets clearer with the solution since you can easyly loop and do whatever instead of multiple <dtml-sendmail> tags.
The solution then would be to write several new chapters that talk about how to do this. - C
On Saturday, December 7, 2002, at 04:11 AM, Tino Wildenhain wrote:
Hi Chris,
--On Freitag, 6. Dezember 2002 21:27 -0500 Chris McDonough <chrism@zope.com> wrote:
On Fri, 2002-12-06 at 19:13, Tino Wildenhain wrote:
These are exactly the things you shouldn't neither do in DTML nor in ZPT :-)
What do you suggest people use for a templating language for email, JavaScript, SQL, etc? I think it's too much to expect them to use Python to do this (esp. wrt SQL methods).
Oh, is it? I'd rather like to write %(name)s %(value)d then <dtml-whatever value> Recently I read the python-dbi spec and its very nice to see what you could do with the above form. There are even standard ways to do multiple querys or function calls. (Hope I can contribute a product for this as time permits)
But SQL Method DTML is very very very very nice. It has a lot of type enforcement/safety measures (ie - autoquoting SQL Strings, ensuring that a 'sqlvar type=float' operation is inserting a float); a lot of *very* nice features for generating 'where' clauses (the sqltest 'optional' flag and the smart '<dtml-and> and <dtml-or>' tags that won't render if an optional 'sqltest' preceding them was not rendered); the 'sqltest multiple' feature is especially nice: <dtml-sqlgroup where> <dtml-sqltest foo type=nb multiple optional> </dtml-sqlgroup> If foo is a blank string or empty list, that will render nothing. If foo is a single string, that renders:: where foo = 'bar' But if foo is a list of strings, that will render:: where foo in ('bar', 'baz') Doing that programatically in Python is counterintuitive and awkward (just as it was before the specialized 'dtml-sql___' tags in DTML). For simple queries, doing it in the host programming language is not bad. But for complex queries, it's very awkward to generate SQL. It's almost as bad as generating HTML inside of a programming language - it becomes difficult to maintain.
For E-Mail and Javascript templates I also find it less confusing if I can use %(var)s form.
It's worth noting that there's a little known DTML format that's of this style. Again - when doing simple insertion, %(var)s is not bad. But once anything fancy comes into play - conditional insertion, looping, etc - maintainability goes out the window when staying in the host programming language. When I was evaluating Roundup <http://roundup.sf.net>, I wanted to generate emails that looked as good as the ones generated by Tracker. I had to write lines and lines and lines of Python code to do it in order to replace a subclassed method. There was no template that I could jigger around. (To be fair to Roundup and Tracker both, I think customizing Tracker's email messages is even harder). I wouldn't mind seeing DTML.String re-emerge, which complements the Python formatting string with DTML constructs to handle more advanced templating needs. If you took a lot of the programming-language style tags (dtml-try, dtml-return) out of DTML and normalized the expression system (ie - to use TALES), you'd have a very usable system. The core design concepts of DTML are good, it's just corrupted itself over the years by stepping out of the plain-text templating language domain and straddling the templating/programming language domains. DTML is even used to generate DTML, by using the Extended Python Format String syntax. This is how the 'Z Search Interface' custom reports are generated.
As a general solution for texts one can use "file" which has an edit tab for several releases of zope now. Then use it like this:
context.thefile.read() % context.REQUEST.form
or whatever seems appropriate to get values from.
E-Mail even gets clearer with the solution since you can easyly loop and do whatever instead of multiple <dtml-sendmail> tags.
Life would be so much better if odd tags like <dtml-sendmail> could just go away, and instead we had 'SMTP Methods' or something like that - mail specific templates that are bound to a mailhost, with special DTML tags (like the mime tag), similar to SQL Methods. I love the SQL Method specific DTML tags. They make writing dynamic SQL statements so easy, especially when compared to _any_ other system that I've seen. It's a good showcase for DTML's ability to turn into a domain specific templating language.
Regards Tino
On 5 Dec 2002, Chris McDonough wrote:
Time has rolled around for me to ask for assistance with editing the most recent edition of the Zope Book. A "2.6 edition" of the Zope Book exists at http://www.zope.org/Documentation/Books/ZopeBook/2_6Edition/index_html. It has many new chapters and a most existing chapters have been rewritten and extended. But it's not finished and I'd really like this Zope Book edition to be the "current" edition by the time Zope 2.6.1 comes out.
...
- Downloading the source version of the chapter via the "STX source" link at the top of the page. Alternatively you might use the get_zope-book Script which I made available some minutes ago at
http://people.debian.org/~tille/packages/zope-book/ besides some Debian packages of the current version of the Zope Book. Thanks for all the authors to the fine work. I know that the Debian community is waiting for you new official release. By the way: I used the StructuredText/* stuff from the old CVS zope-book version. This uses old regsub stuff. I would like to ask whether there is some more recent stuff to convert structured text into HTML or other formats. Kind regards Andreas.
On 6 Dec 2002, Chris McDonough wrote:
Alternatively you might use the get_zope-book Script which I made available some minutes ago at
Nice! Sorry for not making this easier... No need to sorry. ;-) It was a fun to be perhaps a bit helpful. Feel free to enhance the quick hack I did (especially regarding the StructuredText-Regexp problem perhaps).
Kind regards Andreas.
participants (7)
-
Allen Schmidt -
Andreas Jung -
Andreas Tille -
Chris McDonough -
Jeffrey P Shell -
Paul Winkler -
Tino Wildenhain