Is there a book or a place where I can find: a: a DTML programmer's reference, or an API reference, or a TAL reference which contains ALL the objects and methods available to any of these scripting languages? The Zope Book doesn't have such a reference. What it has is very limited and not for a beginner. For instance, let's say I want to learn about something really basic, like what REQUEST.get does. I've searched the Zope 2nd edition book (searched the most likely 4 chapters where I thought I could find this information) and found nothing. I've searched Google on how to use "REQUEST.get" - nothing again that looks like a reference. I could probably find it mentioned in the cookbook in a snippet, but where's the book that has this BASIC stuff in it, indexed, with examples, along with all the other methods of the REQUEST object; and then all the other callable objects as well? Where is the basic Zope documentation? Don't say "The Zope Book" because that jumps from too-basic to extremely complex within one paragraph, and it is missing a comprehensive object.method reference with syntax and examples. There is a need for two Zope books - one to put the screenshots in (a programmer's reference doesn't need screenshots), for absolute beginners, and one programmer's / scripting reference with objects, methods, syntax, and examples. Maybe even three books, the last being the high-level object-oriented architectural python-related stuff that most people don't need to know to write scripts. <flame> Is it the intention of Zope Corporation to limit the use of Zope, by keeping easily understood and useful documentation away from the masses? It sure seems this way. This is my second or third attempt at learning Zope (without knowing Python - BTW, is that a prerequisite?) and each time I am frustrated by the lack of the type of documentation I can easily find for any other language (PHP, C) or a scripting reference (ASP, Javascript) or application framework (Midgard has excellent API documentation). I am amazed that since Zope is all-powerful, that it has not used to build a site comparable to, say, http://www.php.net/docs.php. The wikis are pathetic compared to other collaborative projectware and portalware (www.xoops.org), axisgroupware.org, dev.4arrow.com (a php-based Zope lookalike, although his documentation sucks REALLY bad). I've never seen a calendar in Zope comparable to something like MS Outlook's calendar, which I've seen in other portalware products. Is Zope not up to the task; or is it that nobody except the developers really know how to explain how it's used; or is it that nobody knows how to write documentation? Is it funding? Hell, if someone just copied the table of contents from the PHP site, and then wrote comprehensive Zope documentation around that, you might solve the Zope documentation deficit. And then you would have more people who understood it and all the benefits that would bring to the community. </flame> How people have learned Zope thus far with the documentation available is beyond me. It must be that I didn't grow up learning OOP in computer science like everyone does these days... -Patrick Price
--On Mittwoch, 15. Januar 2003 15:27 -0500 Patrick Price <patrick@wvu.edu> wrote:
Is there a book or a place where I can find:
a: a DTML programmer's reference, or an API reference, or a TAL reference which contains ALL the objects and methods available to any of these scripting languages? The Zope Book doesn't have such a reference. What it has is very limited and not for a beginner.
The Zope Book has a reasonable API references for ZPT, DTML/TAL (Appendix A-C). <flame>
Is it the intention of Zope Corporation to limit the use of Zope, by keeping easily understood and useful documentation away from the masses? It sure seems this way.
Don't blame ZC for the documentation. They invested a fair amount of time and money into the Zope Book. It is not ZC primary task to produce documentation...that's the job of publishers like O'Reiley. -aj
The Zope Book has a reasonable API references for ZPT, DTML/TAL (Appendix A-C).
No Andreas, it does not have that. It has an API reference, but not a comprehensive or reasonable one. Some core functions are simply undocumented. Maybe 10%, maybe less, but they have been undocumented for more than a year, maybe even two years! And there are almost no examples. IMHO every function should have an example. Even the simplest function. A definition is good, but examples are preferred by many. And don't get me started that examples do not belong to reference text. Make them optional, so that they can be turned off by people who dislike examples. Patrick Price sees this deficiency clearly, since he's a newcomer. Zope stalwarts are blind to these issues. I've been using Zope for four years now, and although documentation improved a lot since 1998, it is still the same relative distance from Zope abilities. And Patrick is either right that this is a funding issue, or <sinister=on>Zope Corp. ridiculously high consulting fees depend on the documentation deficiencies.</sinister=off> Patrick needs to download archives of this conference since 2000 and use them as a very valuable resource. He also must go to http://www.zope.org for some issues, and quite often he will need to study Zope source code. That is not a normal situation. That is Zope in 2003, and it should change. -- Milos Prudek
--On Mittwoch, 15. Januar 2003 22:43 +0100 Milos Prudek <milos.prudek@tiscali.cz> wrote:
The Zope Book has a reasonable API references for ZPT, DTML/TAL (Appendix A-C).
No Andreas, it does not have that. It has an API reference, but not a comprehensive or reasonable one. Some core functions are simply undocumented. Maybe 10%, maybe less, but they have been undocumented for more than a year, maybe even two years!
Instead of crying around, you would better help working on the documentation issue. The Zope Book is a more or less open project (Chris McDonough asked several times for support). So everyone is invited to contribute to a better documentation.
And there are almost no examples. IMHO every function should have an example. Even the simplest function. A definition is good, but examples are preferred by many. And don't get me started that examples do not belong to reference text. Make them optional, so that they can be turned off by people who dislike examples.
Patrick Price sees this deficiency clearly, since he's a newcomer. Zope stalwarts are blind to these issues.
I've been using Zope for four years now, and although documentation improved a lot since 1998, it is still the same relative distance from Zope abilities. And Patrick is either right that this is a funding issue, or <sinister=on>Zope Corp. ridiculously high consulting fees depend on the documentation deficiencies.</sinister=off>
ZC is small company and they must make money to survive. First for their own sake and second for the sake of Zope. Without ZC Zope would be nothing so don't complain about their fees. They have a lot of qualified people and I am sure they are worth the money. At least ZC consultants work with more worth than 95% of all consultants I know. -aj
No Andreas, it does not have that. It has an API reference, but not a comprehensive or reasonable one. Some core functions are simply undocumented. Maybe 10%, maybe less, but they have been undocumented for more than a year, maybe even two years!
Instead of crying around, you would better help working on the documentation
I am ready to do that. I have already created some of KDE 2.0 documentation (Kicker, KMenuEdit, KOrganizer): http://g.unsa.edu.ar/opt/kde2/share/doc/HTML/en/kicker/ http://www.kde.org/credits.html However, I cannot do it for free. Creating this type od documentation is much more difficult than user documentation. -- Milos Prudek
First, please see: http://www.zopezen.org/Members/chrism/News_Item.2002-10-28.2851/view ;-) Then see: http://www.zope.org/DocProjects/zope_book_signups/index_html I purposely assigned no one the API reference chapters because I think they can be autogenerated. But this is something that somebody has to do, and I'm so bogged down at the moment, there's no way it's getting done any time soon by myself. Note that ZC is faultless. The volunteers for Zope Book work are doing it on their own dime. If you want to help, please speak up. - C On Wed, 2003-01-15 at 16:43, Milos Prudek wrote:
The Zope Book has a reasonable API references for ZPT, DTML/TAL (Appendix A-C).
No Andreas, it does not have that. It has an API reference, but not a comprehensive or reasonable one. Some core functions are simply undocumented. Maybe 10%, maybe less, but they have been undocumented for more than a year, maybe even two years!
And there are almost no examples. IMHO every function should have an example. Even the simplest function. A definition is good, but examples are preferred by many. And don't get me started that examples do not belong to reference text. Make them optional, so that they can be turned off by people who dislike examples.
Patrick Price sees this deficiency clearly, since he's a newcomer. Zope stalwarts are blind to these issues.
I've been using Zope for four years now, and although documentation improved a lot since 1998, it is still the same relative distance from Zope abilities. And Patrick is either right that this is a funding issue, or <sinister=on>Zope Corp. ridiculously high consulting fees depend on the documentation deficiencies.</sinister=off>
Patrick needs to download archives of this conference since 2000 and use them as a very valuable resource. He also must go to http://www.zope.org for some issues, and quite often he will need to study Zope source code. That is not a normal situation. That is Zope in 2003, and it should change. -- Chris McDonough <chrism@zope.com> Zope Corporation
On Wed, Jan 15, 2003 at 06:22:39PM -0500, Chris McDonough wrote:
I purposely assigned no one the API reference chapters because I think they can be autogenerated.
Oops. Right. Hmmmm. -- Paul Winkler http://www.slinkp.com Look! Up in the sky! It's TURBO TELEVISION OF DESPAIR! (courtesy of isometric.spaceninja.com)
On 15 Jan 2003, Chris McDonough wrote:
I purposely assigned no one the API reference chapters because I think they can be autogenerated. While I perfectly share your idea of autogeneration I see no reason to refuse the work of volunteers to improve the appendix chapters as long as autogeneration does not work.
And, yes, I think that ZC has done a good job and the documentation is done by great volunteers. Thanks to all who provided there spare time to this project. Kind regards Andreas, while uploading a new zope-book Debian package from todays STX sources.
I'm CC'ing Chris McDonough because I don't know who's handling the API section for the 2.6 zope book and there is, I think, a valid point here that relates to that appendix. On Wed, Jan 15, 2003 at 03:27:37PM -0500, Patrick Price wrote:
Is there a book or a place where I can find:
a: a DTML programmer's reference, or an API reference, or a TAL reference which contains ALL the objects and methods available to any of these scripting languages? The Zope Book doesn't have such a reference. What it has is very limited and not for a beginner.
First of all, you should know that the ZB changes often; the 2.6 version ("in progress") adds A LOT of stuff. Including reference sections on ZPT etc. http://www.zope.org/Documentation/Books/ZopeBook/
For instance, let's say I want to learn about something really basic, like what REQUEST.get does. I've searched the Zope 2nd edition book (searched the most likely 4 chapters where I thought I could find this information) and found nothing.
REQUEST has all the methods that python dictionaries have, including "get". IMO this should be somewhere in the API reference, and it is not. All it says is "The request object is a mapping object that represents a collection of variable to value mappings." An experienced python programmer *might* recognize the word "mapping" and guess that REQUEST supports all the Python dictionary methods, which it does. But this is not explicitly stated.
I've searched Google on how to use "REQUEST.get" - nothing again that looks like a reference.
Now that you know that it supports all the methods of dictionaries, you can look up dictionaries in any python reference. :)
paragraph, and it is missing a comprehensive object.method reference with syntax and examples.
There are more examples in the reference sections of the 2.6 book. You are not the first person to ask for them. :)
How people have learned Zope thus far with the documentation available is beyond me.
Trial, error, and mailing lists. :-\ Re. learning zope without learning python: You already ARE using python if you're looking up stuff in the API reference. Zope 2 tried to make it possible to develop websites without learning python. IMO this failed, because the result is that people inevitably end up with snippets of python in their DTML without realizing that's what they're doing. Zope 3 is planning some interesting approaches to this problem. It's designed so that many things can be done with configuration instead of scripting, and a very interesting replacement for ZClasses will provide a (hopefully) very smooth and easy transition from through-the-web developement to pure python code, and you can get work done with any mixture of the two. Currently under discussion on zope3-dev. But don't hold your breath - I wouldn't expect to see a production-quality zope3 for many months. For now: don't fear python, embrace it. It's one of the best things about zope 2. -- Paul Winkler http://www.slinkp.com Look! Up in the sky! It's GHOST - SHIT CORPSE! (courtesy of isometric.spaceninja.com)
On Wed, 2003-01-15 at 19:12, Paul Winkler wrote:
I'm CC'ing Chris McDonough because I don't know who's handling the API section for the 2.6 zope book and there is, I think, a valid point here that relates to that appendix.
Definitely a valid point. The ZB API docs do leave a lot to be desired. Lots of people miss out on the help system online API docs as well. These should likely be merged into a single reference (and the help system should die). But this is a pretty major project, and at this point, I'm inclined to say that it just won't get done by me until maybe 6 months or a year from now (maybe even never) unless someone just steps up to the plate and does it in the meantime. An alternative is to hand-massage the existing ZB API docs into coherency until the project can be embarked upon. - C
At 12:27 PM 1/15/2003, you wrote:
Where is the basic Zope documentation? Don't say "The Zope Book" because that jumps from too-basic to extremely complex within one paragraph, and it is missing a comprehensive object.method reference with syntax and examples. There is a need for two Zope books - one to put the screenshots in (a programmer's reference doesn't need screenshots), for absolute beginners, and one programmer's / scripting reference with objects, methods, syntax, and examples. Maybe even three books, the last being the high-level object-oriented architectural python-related stuff that most people don't need to know to write scripts.
You're right that there is no single source of information available on Zope that takes you through step-by-step. This may change some day, but is the state of things at the moment. It's certainly no worse in this respect that some other projects I could mention and far better than others. Ever tried to read the official documentation for Sendmail? The upside is that there are lot of very knowledgeable, helpful people available who will gladly share the benefits of years spent wrestling with this system. If you want an example of something, you need only ask. Heck, we'll *race* each other to give a useful answer. That may not be as convenient as having full documentation on your bookshelf, but it's open source. Everyone here is trying to be helpful *while doing their regular work*.
<flame> Is it the intention of Zope Corporation to limit the use of Zope, by keeping easily understood and useful documentation away from the masses?
That's a pretty ungenerous allegation. How much did you pay Zope Corp for the ability to use this amazing software? They make a sincere effort to support us and ask very little in return. This isn't Microsoft we're talking about here. :-)
This is my second or third attempt at learning Zope (without knowing Python - BTW, is that a prerequisite?)
I'd say it is, though others may disagree. If you know *any* other language well, you can pick up Python in a day. If you've never programmed before, Python might take a whole week to learn. And it pays off too: the real power of Zope lies not in learning to use DTML but in extending Zope with your own objects. So no, it's not required, but it *is* a major difference between just getting by and actually understanding what's going on.
How people have learned Zope thus far with the documentation available is beyond me.
The same way you learn how to use any open source product: 1. Download the product 2. Read the available documentation 3. Curse the paucity of good documentation 4. Start putting together trivial projects or examples 5. Ask questions of more experienced users 6. Curse the docs some more 7. Attempt a nontrivial project 8. Ask more questions 9. Break down and read the source 10. Gain enlightenment Seems like you're on step 3. :-) Please proceed to step 4 and we'll be happy to help you at step 5 and may even commiserate with you at step 6. HTH, Dylan
I agree with everything everyone said - especially Chris' whine on whining. I have been an unwitting participant in this. I also did not mean to imply anything sinister about Zope Corporation. I was merely ruminating/speculating to give an example of what people might commonly think the situation is, unless it is made clear. In any case, it is indicative of the maturity of the people on this list, that noone took my whiney rant as just a whiney rant - everyone actually gave it consideration. That is amazing and to be congratulated. Now I am committing to myself to re-write a sample chapter to see if I can actually do something about the documentation problem. I find my main complaints with the Zope book are that it uses a lot of things such as "examples", or "what have yous" in a lot of "quotes" which makes it, for example, such as, "hard to read!" Yackety Shmackety, right? I'm not slamming anyone's writing style - just looking for validation that I'm not the only one and that I'm on the right track. This may not be the place for it, but here's my re-write (all original with bits of the original text) of the first part of the "Object Orientation" chapter of the 2.6 book. -Patrick Price Object Orientation There are many programming languages based on Object Orientation (OO), and Zope is based on the Object-Oriented Programming (OOP) language known as Python. To understand and use Zope for creating anything but simple web sites, you must understand how OOP controls every behavior of Zope. Zope's foundation is built on object-orientation, so it follows that if you master OOP, you will master Zope. Object-orientation is a programming paradigm in which all logic (the actual programming and scripting) and data (folders, files, databases, etc. ) are treated as objects. Viewing everything you work with as an abstract object allows you to focus on a high-level view of your application, rather than getting bogged down with details like file descriptors, handles, and other low-level programming chores. You may think of objects as building blocks, which can be comprised of bundles of smaller things such as data, programs, variables - even other objects! By categorizing your data and logic - your problems - as objects, you will find that you can break up large problems into smaller problems, block by block. This level of abstraction helps you develop clear design solutions, perform rapid prototyping, and results in an efficient, well-structured application design. Objects Prior to the OOP paradigm, data was viewed as separate from program code, or sometimes mixed together without a clear delineation between them. Now, with OOP methodology, your data and logic can both be stored in a single object. Objects provide a clear and distinct separation of data and logic within themselves. Zope treats every thing as an object, whether it is, for example: a filesystem directory, a folder (container for other objects), files, modules, products, templates, forms, spreadsheets, spreadsheet cells, databases, database records, phone #'s, addresses, scripts, programs, calendars, buttons, URL's - Anything! There really is no limit to what can be called and modeled as an object. In your journey to understanding Zope's object-oriented framework, you may continue to think that data is just that - plain old data. You must leave those thoughts behind. Once anything - even a simple text file - is stored in Zope, it becomes an object. The associated details of the file, such as the file type, size, and location are stored along with it and become collectively known as the attributes of the object. Even the file data itself is considered an attribute of this newly-created file object. In the same manner a mere program becomes an object when it is stored in Zope. Programming, scripting, code, logic - are then referred to as the methods of the object. Thus, an object is comprised of attributes and methods.
On Thu, 2003-01-16 at 10:06, Patrick Price wrote:
Now I am committing to myself to re-write a sample chapter to see if I can actually do something about the documentation problem.
Thanks!
I find my main complaints with the Zope book are that it uses a lot of things such as "examples", or "what have yous" in a lot of "quotes" which makes it, for example, such as, "hard to read!" Yackety Shmackety, right? I'm not slamming anyone's writing style - just looking for validation that I'm not the only one and that I'm on the right track.
This is a valid complaint.. Now that I've read it again, "quoting" is somewhat overused. I am largely unaware of doing this when I am writing. I think in most cases, my purpose in doing so is to ensure that folks know a word that I'm using is a "normal" word instead of some kind of domain-specific keyword that has a formal definition that they need to understand.
This may not be the place for it, but here's my re-write (all original with bits of the original text) of the first part of the "Object Orientation" chapter of the 2.6 book. -Patrick Price
This probably isnt the place for it, but I do appreciate the effort. If you get motivated to do more editing, please send me the entire chapter via email and if it makes sense, I will re-edit what you've done for inclusion in the book when possible. Below I comment on your edits. I hope you don't mind that I point out some flaws in your rewrite.
Object Orientation
There are many programming languages based on Object Orientation (OO), and Zope is based on the Object-Oriented Programming (OOP) language known as Python. To understand and use Zope for creating anything but simple web sites, you must understand how OOP controls every behavior of Zope. Zope's foundation is built on object-orientation, so it follows that if you master OOP, you will master Zope.
OOP doesn't control every behavior of Zope, although it does permeate Zope. For example, there is lots of procedural code in a typical Zope application.
Object-orientation is a programming paradigm in which all logic (the actual programming and scripting) and data (folders, files, databases, etc. ) are treated as objects.
Does it make sense to define object orientation as a system in which things are "treated as objects"? This sounds a little sketchy. ;-)
Viewing everything you work with as an abstract object allows you to focus on a high-level view of your application, rather than getting bogged down with details like file descriptors, handles, and other low-level programming chores.
This is a good sentence.
You may think of objects as building blocks, which can be comprised of bundles of smaller things such as data, programs, variables - even other objects! By categorizing your data and logic - your problems - as objects, you will find that you can break up large problems into smaller problems, block by block.
I'm not sure how this is any more clear than what the current chapter says.
This level of abstraction helps you develop clear design solutions, perform rapid prototyping, and results in an efficient, well-structured application design.
Objects themselves help you do none of these things, although proper usage of objects in an overall application design does.
Objects
Prior to the OOP paradigm, data was viewed as separate from program code, or sometimes mixed together without a clear delineation between them. Now, with OOP methodology, your data and logic can both be stored in a single object.
This makes it sound as if OOP is a new dishwashing detergent. ;-) OOP implementations have been around since at least 1962 (Simula was the first OO programming language), and it's likely that the concept existed before that.
Objects provide a clear and distinct separation of data and logic within themselves. Zope treats every thing as an object, whether it is, for example: a filesystem directory, a folder (container for other objects), files, modules, products, templates, forms, spreadsheets, spreadsheet cells, databases, database records, phone #'s, addresses, scripts, programs, calendars, buttons, URL's - Anything!
Zope doesn't treat these things as objects at all. Your code might, but Zope knows nothing about them as objects until you teach it to do so.
There really is no limit to what can be called and modeled as an object.
This is a nonsentence. ;-)
In your journey to understanding Zope's object-oriented framework, you may continue to think that data is just that - plain old data. You must leave those thoughts behind.
No. You don't need to leave them behind. Zope works with "flat" data too (via RDB).
Once anything - even a simple text file - is stored in Zope, it becomes an object.
This is arguable. What does "stored in Zope" mean? I realize that it's a simplified example and what you probably really mean is "items that are visible in the Zope management interface which are instances of classes, stored in the Zope object database", but this more detailed description is obviously too much to chew off conceptually for the reader in this chapter. It might be best to just not go here. This is a chapter primarily describing object orientation, and isn't as much about how it relates to Zope.
The associated details of the file, such as the file type, size, and location are stored along with it and become collectively known as the attributes of the object. Even the file data itself is considered an attribute of this newly-created file object.
This is a good example...
In the same manner a mere program becomes an object when it is stored in Zope. Programming, scripting, code, logic - are then referred to as the methods of the object.
What are referred to? What object?
Thus, an object is comprised of attributes and methods.
You don't define "method" at all. Cheers, - C
Crap! I suck! I obviously don't know what I'm talking about. I'll keep trying though. -Patrick Chris McDonough wrote:
On Thu, 2003-01-16 at 10:06, Patrick Price wrote:
Below I comment on your edits. I hope you don't mind that I point out some flaws in your rewrite.
No, you don't! You stepped up to the plate. ;-) That's a hard thing to do. Writing docs is hard. Keep trying! On Thu, 2003-01-16 at 11:15, Patrick Price wrote:
Crap! I suck! I obviously don't know what I'm talking about. I'll keep trying though. -Patrick
Chris McDonough wrote:
On Thu, 2003-01-16 at 10:06, Patrick Price wrote:
Below I comment on your edits. I hope you don't mind that I point out some flaws in your rewrite.
_______________________________________________ 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 ) -- Chris McDonough <chrism@zope.com> Zope Corporation
At 12:03 PM 1/16/2003, you wrote:
Dylan Reinhardt wrote at 2003-1-15 20:04 -0800:
... Ever tried to read the official documentation for Sendmail? Yes. It is good.
Yes, it's wonderful... it's also mostly impenetrable to people who aren't already familiar with how sendmail and *nix work. Docs like this (http://www.sendmail.org/m4/masquerading.html) are very clear and concise for experienced admins. A beginner could read this ten times and still not know where/how these settings are supposed to be made or how to have sendmail recognize the changes. If you administer sendmail, you take several steps for granted and the docs reflect this. This is very tough stuff for beginners to get a handle on. Dylan
Patrick Price wrote at 2003-1-15 15:27 -0500:
Is there a book or a place where I can find:
a: a DTML programmer's reference, or an API reference, or a TAL reference which contains ALL the objects and methods available to any of these scripting languages? The Zope Book doesn't have such a reference. What it has is very limited and not for a beginner. What you want is not for a beginner either...
The reference would contain hundreds of classes and thousands of methods. Few beginners would not read it and fewer understand it... Use "DocFinder" (--> <http://www.dieter.handshake.de/pyprojects/zope>) to get a feeling of what you are looking for!
For instance, let's say I want to learn about something really basic, like what REQUEST.get does. There are things that are so natural that there is no need to document them!
"get" is a generic mapping method. It has "key" as parameter and an optional default parameter (with default value "None"). It returns the value mapped to "key" or the default (if "key" is not mapped). You find this information in the Python library reference. "REQUEST" is a mapping. Thus, you know, what "REQUEST.get" does.
... Where is the basic Zope documentation? Don't say "The Zope Book" because that jumps from too-basic to extremely complex within one paragraph, There will never be a documentation that answers all your potential questions. If there were such a documentation, it would be so huge that you would not find the answers to your questions.
and it is missing a comprehensive object.method reference with syntax and examples. The size would be similar to that of the Oracle documentation: several meters of documentation...
Dieter
Am 16.01.2003, 21:43 Uhr schrieb Dieter Maurer: -----------------------------------
Patrick Price wrote at 2003-1-15 15:27 -0500: [...]
For instance, let's say I want to learn about something really basic, like what REQUEST.get does.
There are things that are so natural that there is no need to document them!
That's a typical viewpoint of a "guru".
"get" is a generic mapping method. It has "key" as parameter and an optional default parameter (with default value "None"). It returns the value mapped to "key" or the default (if "key" is not mapped). You find this information in the Python library reference.
"REQUEST" is a mapping.
Would it be asking too much or be inappropriate to put something similar to your short explanation into the first paragraph of the ref-doc of the class REQUEST? Maybe just something like: REQUEST is a python mapping/dictionary. It supports all methods, that mappings/dictionaries do. (I'm only a python/zope newbie, so my version is "newbie-speak", so don't hit me, if there's something wrong about that ;-) When you're trying to find out, what sort of things you can do with REQUEST, then you'll check the API Reference. And if you don't know that REQUEST is mapping, it could take you a lot of time to 'find' even basic methods like "get". Hon.
On Fri, 2003-01-17 at 03:59, Thieu-Hon Tran wrote:
Would it be asking too much or be inappropriate to put something similar to your short explanation into the first paragraph of the ref-doc of the class REQUEST? Maybe just something like:
REQUEST is a python mapping/dictionary. It supports all methods, that mappings/dictionaries do.
You can do this yourself, at least for the Zope Book. The online version of the Zope Book 2.5 edition accepts comments, and REQUEST is documented in one of its appendixes. It would be helpful to have this comment in here so it can be included as "real" text into the 2.6 Zope Book. The help system API docs however are currently completely unmaintained and likely to stay that way for eternity or until someone puts them out of their misery or signs up to maintain them out of the kindness of their heart. - C
Chris McDonough wrote:
On Fri, 2003-01-17 at 03:59, Thieu-Hon Tran wrote:
Would it be asking too much or be inappropriate to put something similar to your short explanation into the first paragraph of the ref-doc of the class REQUEST? Maybe just something like:
You can do this yourself, at least for the Zope Book. The online
You can, but sometimes your comments will be ignored. Example: June 20, 2002, Anonymous user comments that "manage_addDocument should be manage_addDTMLDocument! if you use manage_addDocument, you´ll get a DTML Method..." Jan 10, 2003, Anonymous user comments that "manage_addDocument creates a DTML Method. manage_addDTMLDocument creates a DTML document. This has been pointed out 6 months ago, and still no change in Zope Book." Maybe the reasoning here is that since it is in the comments, it does not need to be integrated in Zope Book. I do not agree with this reasoning. Such valid comments should be integrated in the Book and deleted from comments. Another example: manage_delObjects. Why is this method top secret? It is IMHO quite essential method. And it was pointed out in comments by xqvverty - Sep. 13, 2002 9:53 pm. IMHO documentation should be managed by a full-time employee. Chris is doing it, bot certainly not full-time. I even believe that this job should not be carried out by anyone directly developing Zope. I've been in both shoes, working sometimes as developer, sometimes as a documenter, and sometimes both. In my experience, I was a poor documenter of my own work. Programmers seldom create good documentation of their own work. Documenter should be independent, and should have free access to the developers to ask questions. -- Milos Prudek
Have you noticed that for the 2.6 edition of the Zope Book at http://www.zope.org/Documentation/Books/ZopeBook/2_6Edition, we've addressed and edited out all of the comments in every chapter so far except for three "main" chapters and the API ref? Many people have helped to do this. It has taken on the order of maybe... 600 man-hours to do this. The remaining three "main" chapters are in progress. The API ref isn't, but should be, and adding a comment to it in the 2.5 edition will make sure it doesn't get lost in the email ether. Just because a comment is old doesn't mean it won't get addressed. This stuff takes time. And yes, I you're absolutely right. In a perfect world, someone other than a developer whould edit the Book, and yes, it would be a paid full time job. But things are the way they are, and nobody is willing to pay for it. ZC isn't willing to pay for it, nor should it be their obligation to do so. Are you? Annoyed, - C On Fri, 2003-01-17 at 08:54, Milos Prudek wrote:
Chris McDonough wrote:
On Fri, 2003-01-17 at 03:59, Thieu-Hon Tran wrote:
Would it be asking too much or be inappropriate to put something similar to your short explanation into the first paragraph of the ref-doc of the class REQUEST? Maybe just something like:
You can do this yourself, at least for the Zope Book. The online
You can, but sometimes your comments will be ignored.
Example:
June 20, 2002, Anonymous user comments that "manage_addDocument should be manage_addDTMLDocument! if you use manage_addDocument, you´ll get a DTML Method..."
Jan 10, 2003, Anonymous user comments that "manage_addDocument creates a DTML Method. manage_addDTMLDocument creates a DTML document. This has been pointed out 6 months ago, and still no change in Zope Book."
Maybe the reasoning here is that since it is in the comments, it does not need to be integrated in Zope Book. I do not agree with this reasoning. Such valid comments should be integrated in the Book and deleted from comments.
Another example:
manage_delObjects. Why is this method top secret? It is IMHO quite essential method. And it was pointed out in comments by xqvverty - Sep. 13, 2002 9:53 pm.
IMHO documentation should be managed by a full-time employee. Chris is doing it, bot certainly not full-time. I even believe that this job should not be carried out by anyone directly developing Zope.
I've been in both shoes, working sometimes as developer, sometimes as a documenter, and sometimes both. In my experience, I was a poor documenter of my own work. Programmers seldom create good documentation of their own work. Documenter should be independent, and should have free access to the developers to ask questions. -- Chris McDonough <chrism@zope.com> Zope Corporation
Chris McDonough wrote:
Have you noticed that for the 2.6 edition of the Zope Book at http://www.zope.org/Documentation/Books/ZopeBook/2_6Edition, we've addressed and edited out all of the comments in every chapter so far except for three "main" chapters and the API ref? Many people have
I have not. Great job!
time job. But things are the way they are, and nobody is willing to pay for it. ZC isn't willing to pay for it, nor should it be their obligation to do so. Are you?
I'm not, but I'm perfectly ready and willing to do this as a full time or part time paid job remotely from Czech republic and my salary would be quite reasonable given lower expenses in CZ. Mail me directly if you want to see examples of my work. As for money, I already contributed work in lieu of money. Besides creating some core KDE 2.0 documentation for free, I also translated 70+ pages of core Open Source advocacy text "Why Open Source Software / Free Software (OSS/FS)? Look at the Numbers!" (http://www.dwheeler.com/oss_fs_why.html) into Czech at no charge, maintained it to be current and I am hosting it for free. This job alone is worth $1200 at the current market price for transation services.
Annoyed,
Don't be. Take me with a large spoon of salt :-) -- Milos Prudek
On Fri, 2003-01-17 at 09:47, Milos Prudek wrote:
Have you noticed that for the 2.6 edition of the Zope Book at http://www.zope.org/Documentation/Books/ZopeBook/2_6Edition, we've addressed and edited out all of the comments in every chapter so far except for three "main" chapters and the API ref? Many people have
I have not. Great job!
Thanks! ;-)
I'm not, but I'm perfectly ready and willing to do this as a full time or part time paid job remotely from Czech republic and my salary would be quite reasonable given lower expenses in CZ. Mail me directly if you want to see examples of my work.
I've looked at your kicker docs and they seem quite nice. I will ask ZC mgmt about it, but the answer will almost certainly be "we aren't paying anything right now to maintain Zope docs," as it has been for the last year or so. I can't say I completely agree with that decision, but I can't begrudge the sentiment considering the state of the economy, and I certainly don't think they are obligated to maintain *any* docs. There are also a tremendous number of community contributors to the Zope Book 2.6 edition who have come up with some pretty incredible things. See the preface for their names and what they've done. All in all, I think the book is coming along quite nicely without funding or a full-time editor, although it's probably not sustainable in the long term to not have someone who gets paid be responsible for docs. Or maybe it is. Who knows? -- Chris McDonough <chrism@zope.com> Zope Corporation
mgmt about it, but the answer will almost certainly be "we aren't paying anything right now to maintain Zope docs," as it has been for the last
I know.
full-time editor, although it's probably not sustainable in the long term to not have someone who gets paid be responsible for docs. Or maybe it is. Who knows?
Yeah, that's true. I'd have liked Zope to have a wider appeal but I do not directly dispute Zope Corp. decisions. After all, I'm using Zope for free. -- Milos Prudek
Speaking only for myself and Peter Saibaini (sp?), when we tackled the Advanced Scripting chapter for the 2.6 version, we really did try to address *all* comments except a very few that seemed really irrelevant to the chapter. There is now a *lot* more stuff about zope API methods in this chapter. On Fri, Jan 17, 2003 at 02:54:30PM +0100, Milos Prudek wrote:
Chris McDonough wrote:
On Fri, 2003-01-17 at 03:59, Thieu-Hon Tran wrote:
Would it be asking too much or be inappropriate to put something similar to your short explanation into the first paragraph of the ref-doc of the class REQUEST? Maybe just something like:
You can do this yourself, at least for the Zope Book. The online
You can, but sometimes your comments will be ignored.
Example:
June 20, 2002, Anonymous user comments that "manage_addDocument should be manage_addDTMLDocument! if you use manage_addDocument, you?ll get a DTML Method..."
Jan 10, 2003, Anonymous user comments that "manage_addDocument creates a DTML Method. manage_addDTMLDocument creates a DTML document. This has been pointed out 6 months ago, and still no change in Zope Book."
Maybe the reasoning here is that since it is in the comments, it does not need to be integrated in Zope Book. I do not agree with this reasoning. Such valid comments should be integrated in the Book and deleted from comments.
Another example:
manage_delObjects. Why is this method top secret? It is IMHO quite essential method. And it was pointed out in comments by xqvverty - Sep. 13, 2002 9:53 pm.
IMHO documentation should be managed by a full-time employee. Chris is doing it, bot certainly not full-time. I even believe that this job should not be carried out by anyone directly developing Zope.
I've been in both shoes, working sometimes as developer, sometimes as a documenter, and sometimes both. In my experience, I was a poor documenter of my own work. Programmers seldom create good documentation of their own work. Documenter should be independent, and should have free access to the developers to ask questions.
-- Milos Prudek
_______________________________________________ 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 )
-- Paul Winkler http://www.slinkp.com Look! Up in the sky! It's MEGA ENERGY WARRIOR SNAKE! (courtesy of isometric.spaceninja.com)
Thieu-Hon Tran wrote at 2003-1-17 09:59 +0100:
... Would it be asking too much or be inappropriate to put something similar to your short explanation into the first paragraph of the ref-doc of the class REQUEST? Maybe just something like:
REQUEST is a python mapping/dictionary. It supports all methods, that mappings/dictionaries do. This should become:
REQUEST behaves like a python mapping. It supports the following generic mapping methods: "get", subscription ("[...]"), "keys", "values", "items" and "has_key". Dieter
Dieter Maurer wrote:
Patrick Price wrote at 2003-1-15 15:27 -0500: ....
Use "DocFinder" (--> <http://www.dieter.handshake.de/pyprojects/zope>) to get a feeling of what you are looking for!
I tried DocFinder (currently for ZWiki) and i really like it. Everything from ZWiki and from Zope where ZWiki relies on is shown. Recommendation! Thanky you so much for this tool, Dieter. Cheers, Florian -- Florian Konnertz --- http://www.florian-konnertz.de ------------------------------------------------------- http://openspirit.homelinux.net/noowiki/FrontPage Improved ZWiki about all topics, especially consciousness research and wisdom traditions http://www.openmovie.org multimedia project Have a nice day!
participants (10)
-
Andreas Jung -
Andreas Tille -
Chris McDonough -
Dieter Maurer -
Dylan Reinhardt -
Florian Konnertz -
Milos Prudek -
Patrick Price -
Paul Winkler -
Thieu-Hon Tran