Re: [Zope3-Users] Building an admin interface

2007-07-17 Thread Hermann Himmelbauer
Am Montag, 16. Juli 2007 22:44 schrieb Stephan Richter:
 On Monday 16 July 2007 15:58, Benji York wrote:
  This reminds me of something I've been curious about but haven't had
  time to research lately.  What are the differences between pagelets and
  viewlets and their various strengths/weaknesses.  An acceptable answer
  is read the docs and decide for yourself. wink

 Viewlets-pure UI design is a great approach, if you have portal, where
 there is really never a main content area, since you can reuse viewlets
 accross many pages. So in this UI pattern, you would create a Contents
 viewlet manager, and register viewlets for this manager. Depending on which
 page you are looking at, viewlets are picked up and displayed.
 Unfortunately, for simple pages, this requires two directives: One to
 define the page and one to define its Contents viewlet. This cost is very
 acceptable to a portal site where those simple pages are rare, but are
 impractical for more traditional Web applications.

 Also, any piece of dynamic code is a viewlet manager with viewlets or a
 simple content provider: left menu, right menu, header, CSS files, JS
 files, title, etc.

 Pagelet-based UI design is pretty much the same pattern, except that it
 allows you to define a main content area. Here you define a layout template
 that is used to define the O-wrap (pretty much like standard_macros/page).
 A page is then registered as a pagelet, which defines a second template
 that defines the content area of the page. As for macros, the advantage
 here is that you only need one generic UI layout directive plus one other
 directive per page. But something that is much nicer in pagelets is that
 you do not have to include the macro from within the pagelet, but that the
 layout is driving everything. Also, it is much simpler to register an
 alternative layout template for a particular view or context.

That leads me to the question if it's possible to mix pagelets/viewlets? In my 
case, I have one main content area but I have some dynamic code, e.g. a 
navigation box, a login box, later perhaps a search box etc. How would I 
implement them? Perhaps I use a viewlet manager / viewlet in the layout 
template?

Best Regards,
Hermann

-- 
[EMAIL PROTECTED]
GPG key ID: 299893C7 (on keyservers)
FP: 0124 2584 8809 EF2A DBF9  4902 64B4 D16B 2998 93C7
___
Zope3-users mailing list
Zope3-users@zope.org
http://mail.zope.org/mailman/listinfo/zope3-users


Re: [Zope3-Users] Zope3 PID file ?

2007-07-17 Thread Adam Groszer
Hello Thierry,

What about zopectl logreopen?

Tuesday, July 17, 2007, 11:17:50 AM, you wrote:

TF   Hi,

TF I need to write scripts to handle Zope3 logfiles rotation.
TF But I can't find any PID file for the running instance.
TF Do I have to call for Zope restart or is there any other way which could
TF avoid restarting Zope and flushing all caches ?

TF Thanks for any advise,

TF   Thierry Florac


-- 
Best regards,
 Groszer Adam

___
Zope3-users mailing list
Zope3-users@zope.org
http://mail.zope.org/mailman/listinfo/zope3-users


Re: [Zope3-Users] Building an admin interface

2007-07-17 Thread Darryl Cousins
Hi,

On Tue, 2007-07-17 at 08:45 +0200, Hermann Himmelbauer wrote:
 Am Montag, 16. Juli 2007 22:44 schrieb Stephan Richter:
  On Monday 16 July 2007 15:58, Benji York wrote:
   This reminds me of something I've been curious about but haven't had
   time to research lately.  What are the differences between pagelets and
   viewlets and their various strengths/weaknesses.  An acceptable answer
   is read the docs and decide for yourself. wink

snip

 That leads me to the question if it's possible to mix pagelets/viewlets? In 
 my 
 case, I have one main content area but I have some dynamic code, e.g. a 
 navigation box, a login box, later perhaps a search box etc. How would I 
 implement them? Perhaps I use a viewlet manager / viewlet in the layout 
 template?

I recommend reading the README's of z3c.template and z3c.pagelet (and
z3c.macro for good measure). Also study of z3c.formdemo teaches much
about the patterns developed in the z3c packages.

But I think I can answer your question.

1. Register a layout template to your layer using z3c:layout (see
z3c.formdemo/skin for an example)
2. It could contain:

tal:block replace=structure provider:leftcol /!--dynamic code --
tal:block replace=structure provider:pagelet /!-- content area --
tal:block replace=structure provider:rightcol /!--dynamic code --

3. left and right columns are your own viewlet managers registered with
browser:viewletManager
4. `pagelet` is special, you can register a view using z3c:pagelet (and
a template for it with z3c:template) and the `pagelet` provider will do
the rest.

This pattern is used in z3c.formdemo.

Hope this helps.
Regards,
Darryl

 Best Regards,
 Hermann
 

___
Zope3-users mailing list
Zope3-users@zope.org
http://mail.zope.org/mailman/listinfo/zope3-users


Re: [Zope3-Users] Zope3 PID file ?

2007-07-17 Thread Thierry Florac
Tuesday, July 17, 2007, 11:17:50 AM, you wrote:
 
 TF   Hi,
 
 TF I need to write scripts to handle Zope3 logfiles rotation.
 TF But I can't find any PID file for the running instance.
 TF Do I have to call for Zope restart or is there any other way which
 could
 TF avoid restarting Zope and flushing all caches ?


Le mardi 17 juillet 2007 à 11:48 +0200, Adam Groszer a écrit :

 What about zopectl logreopen?
 

zopectl logreopen works, but it seems that a SIGUSR2 signal is sent
and that the whole Zope process is respawned.
So I don't see any difference with zopectl restart... :-(

Am I wrong ?

  Thierry Florac
-- 
  Chef de projet intranet/internet
  Office National des Forêts - Département Informatique
  2, Avenue de Saint-Mandé
  75570 PARIS Cedex 12
  Mél : [EMAIL PROTECTED]
  Tél. : +33 01.40.19.59.64
  Fax. : +33 01.40.19.59.85

___
Zope3-users mailing list
Zope3-users@zope.org
http://mail.zope.org/mailman/listinfo/zope3-users


Re: [Zope3-Users] Building an admin interface

2007-07-17 Thread Stephan Richter
On Tuesday 17 July 2007 02:45, Hermann Himmelbauer wrote:
 That leads me to the question if it's possible to mix pagelets/viewlets? In
 my case, I have one main content area but I have some dynamic code, e.g. a
 navigation box, a login box, later perhaps a search box etc. How would I
 implement them? Perhaps I use a viewlet manager / viewlet in the layout
 template?

Exactely. Of course we use viewlet managers in pagelet-based UI design as 
well.

Regards,
Stephan
-- 
Stephan Richter
CBU Physics  Chemistry (B.S.) / Tufts Physics (Ph.D. student)
Web2k - Web Software Design, Development and Training
___
Zope3-users mailing list
Zope3-users@zope.org
http://mail.zope.org/mailman/listinfo/zope3-users


Re: [Zope3-Users] Re: AW: View or content provider

2007-07-17 Thread Stephan Richter
On Monday 16 July 2007 19:32, Daniel Nouri wrote:
  I do not recommend using views for content that is only
  used inside a template. Because context/@@viewname
  is also traversable as a real view and will probably show
  up in google.

 How would it show up in Google?  Google bots don't try arbitrary URLs, they
 follow links.

 Using ordinary views for parts of a HTML page works perfectly for me.

It works at the cost of security. How do you know that noone will figure out 
those views? And how do you know that they are properly secured, if you never 
test them standalone? This might not be too problematic for a single project, 
but would you like to install a package and suddenly get all those views that 
you do not know whether they are properly secured and may reveal sensitive 
information? I can tell you that some of my clients do care about this!

Regards,
Stephan
-- 
Stephan Richter
CBU Physics  Chemistry (B.S.) / Tufts Physics (Ph.D. student)
Web2k - Web Software Design, Development and Training
___
Zope3-users mailing list
Zope3-users@zope.org
http://mail.zope.org/mailman/listinfo/zope3-users


Re: [Zope3-Users] Zope3 PID file ?

2007-07-17 Thread Thierry Florac
Le mardi 17 juillet 2007 à 12:23 +0200, Martijn Pieters a écrit :
 On 7/17/07, Thierry Florac [EMAIL PROTECTED] wrote:
   What about zopectl logreopen?
  
 
  zopectl logreopen works, but it seems that a SIGUSR2 signal is sent
  and that the whole Zope process is respawned.
  So I don't see any difference with zopectl restart... :-(
 
  Am I wrong ?
 
 You are. There is a SIGUSR2 handler in Signals.Signals, which calls
 the 'reopen' method on all active loggers..
 
 Nowhere is there a signal handler that restarts Zope on SIGUSR2.
 SIGHUP will cause a restart, SIGINT a shutdown, and SIGTERM a fast
 shutdown.
 

My comment was just based on what I can see in z3.log after running
zopectl logreopen :

--
2007-07-17T14:19:42 INFO ZEO.ClientStorage (14916) ClientStorage
(pid=14916) created RW/normal for storage: 'www'
--
2007-07-17T14:19:42 INFO ZEO.cache reusing persistent cache file
'/var/local/zope/zeo1-www.zec'
--
2007-07-17T14:19:46 INFO ZEO.ClientStorage (14916) Testing connection
ManagedClientConnection ('127.0.0.1', 8100)
--
2007-07-17T14:19:46 INFO ZEO.zrpc.Connection(C) (localhost:8100)
received handshake 'Z303'
--
2007-07-17T14:19:46 INFO ZEO.ClientStorage (14916) Server authentication
protocol None
--
2007-07-17T14:19:46 INFO ZEO.ClientStorage (14916) Connected to storage:
('localhost', 8100)
--
2007-07-17T14:19:46 INFO ZEO.ClientStorage (14916) No verification
necessary (last_inval_tid up-to-date)
--
2007-07-17T14:19:47 INFO ZEO.ClientStorage (14916) ClientStorage
(pid=14916) created RW/normal for storage: 'www'
--
2007-07-17T14:19:47 INFO ZEO.cache created temporary cache file
'fdopen'
--
2007-07-17T14:19:47 INFO ZEO.ClientStorage (14916) Testing connection
ManagedClientConnection ('127.0.0.1', 8100)
--
2007-07-17T14:19:47 INFO ZEO.zrpc.Connection(C) (localhost:8100)
received handshake 'Z303'
--
2007-07-17T14:19:47 INFO ZEO.ClientStorage (14916) Server authentication
protocol None
--
2007-07-17T14:19:47 INFO ZEO.ClientStorage (14916) Connected to storage:
('localhost', 8100)
--
2007-07-17T14:19:47 INFO ZEO.ClientStorage (14916) Verifying cache
--
2007-07-17T14:19:47 INFO ZEO.ClientStorage (14916) endVerify finishing
--
2007-07-17T14:19:47 INFO ZEO.ClientStorage (14916) endVerify finished
--
2007-07-17T14:19:47 INFO root -- HTTP:localhost:8080 Server started.
Hostname: localhost
Port: 8080
--
2007-07-17T14:19:47 INFO root Startup time: 22.791 sec real, 17.310 sec
CPU


This output is just the same as what I can read when starting Zope.
Also, as you can see, I'm using a ZEO client storage and Twisted web
server ; I only found logreopen and SIGUSR2 references in ZDaemon
source code, and I thought that default server for Zope-3.3.1 was
Twisted...

Thanks (as always) for any complement...

  Thierry Florac
-- 
  Chef de projet intranet/internet
  Office National des Forêts - Département Informatique
  2, Avenue de Saint-Mandé
  75570 PARIS Cedex 12
  Mél : [EMAIL PROTECTED]
  Tél. : +33 01.40.19.59.64
  Fax. : +33 01.40.19.59.85

___
Zope3-users mailing list
Zope3-users@zope.org
http://mail.zope.org/mailman/listinfo/zope3-users


[Zope3-Users] z3c.zalchemy / z3c.sqlalchemy

2007-07-17 Thread Thierry Florac

  Hi,

I'm looking for packages to ease integration of SQLAlchemy and Zope3.
I found the two references listed into this message's subject and was
wondering if there was any link between then, if both of them are
up-to-date and actively maintained, and what where the benefits of using
any or both of them...

Thanks for any information.

  Thierry Florac
-- 
  Chef de projet intranet/internet
  Office National des Forêts - Département Informatique
  2, Avenue de Saint-Mandé
  75570 PARIS Cedex 12
  Mél : [EMAIL PROTECTED]
  Tél. : +33 01.40.19.59.64
  Fax. : +33 01.40.19.59.85

___
Zope3-users mailing list
Zope3-users@zope.org
http://mail.zope.org/mailman/listinfo/zope3-users


Re: [Zope3-Users] z3c.zalchemy / z3c.sqlalchemy

2007-07-17 Thread Andreas Jung



--On 17. Juli 2007 14:43:27 +0200 Thierry Florac [EMAIL PROTECTED] 
wrote:




  Hi,

I'm looking for packages to ease integration of SQLAlchemy and Zope3.
I found the two references listed into this message's subject and was
wondering if there was any link between then, if both of them are
up-to-date and actively maintained, and what where the benefits of using
any or both of them...


z3c.sqlalchemy (written by myself) is actively maintained in will be used
in several upcoming projects. The goals and usecases covered by 
z3c.sqlalchemy are documented on the cheeseshop project page. z3c.zalchemy 
isn't actively maintained as far from what I heard some weeks ago. 
z3c.zalchemy tries to approach problems I did not have or I did not 
understand. It's a bit more Zope 3 oriented while z3c.sqlalchemy works

fine on Zope 2 and Zope 3. To add another choice: collective.lead by
Martin Aspeli.

-aj

pgpz0jrfWHeLG.pgp
Description: PGP signature
___
Zope3-users mailing list
Zope3-users@zope.org
http://mail.zope.org/mailman/listinfo/zope3-users


[Zope3-Users] Re: AW: Re: AW: View or content provider

2007-07-17 Thread Daniel Nouri
Hi!

Roger Ineichen wrote:
 I do not recommend using views for content that is only 
 used inside a 
 template. Because context/@@viewname
 is also traversable as a real view and will probably show up in 
 google.
 How would it show up in Google?  Google bots don't try 
 arbitrary URLs, they follow links.
 
 This could happen if you update a project and remove a public view 
 called detail.html and register a inline view with the same 
 name whihc you liek to use for calling in ZPT. Just kidding.
 I know this doesn't happen in a project, but are you realy sure.
 
 What's the benefit to register views and call them in ZPT 
 like tal:content=structure context/@@foo_bar ?

 For beeing fair, 
 one benfit is probably the usage of memcached. Such views allows 
 you to easy cache them self, because they are traversable by it's 
 own url. But be carfully, probably they should get cached just 
 once from a unique url and not on different urls used in each view.

Yes, caching is one of my main motivations here.  The unique URL / different
URL caching problem is one that viewlets have as well, AFAICT.

One big plus that you're leaving out is the reusability, just like with
viewlets.  In fact, I believe that with my approach, I have most of the
benefits that zope.viewlets have.  And I in many cases I can get away with
registrations that are more intuitive to work with than the quadruple
adapters + managers that viewlets use.

 Using ordinary views for parts of a HTML page works perfectly for me.
 
 Of corse it's possible to do that, but this doesn't mean it's a good
 concept in every usecase. 
 
 My note on that topic should not say don't use it, it should only make
 people think about the options we have in z3 and point on some side effects?

Sure, I agree that this a good thing.  However, I thought that there must be
better arguments for using viewlets than the traversable / not traversable one.


Daniel

___
Zope3-users mailing list
Zope3-users@zope.org
http://mail.zope.org/mailman/listinfo/zope3-users


[Zope3-Users] Re: AW: View or content provider

2007-07-17 Thread Daniel Nouri
Hi!

Stephan Richter wrote:
 On Monday 16 July 2007 19:32, Daniel Nouri wrote:
 I do not recommend using views for content that is only
 used inside a template. Because context/@@viewname
 is also traversable as a real view and will probably show
 up in google.
 How would it show up in Google?  Google bots don't try arbitrary URLs, they
 follow links.

 Using ordinary views for parts of a HTML page works perfectly for me.
 
 It works at the cost of security. How do you know that noone will figure out 
 those views? And how do you know that they are properly secured, if you never 
 test them standalone? This might not be too problematic for a single project, 
 but would you like to install a package and suddenly get all those views that 
 you do not know whether they are properly secured and may reveal sensitive 
 information? I can tell you that some of my clients do care about this!

How exactly is it easier to secure a viewlet over securing a view?  The fact
that they're traversable doesn't mean that they have to be visible for
everyone, does it?  Am I missing something here?


Regards
Daniel

___
Zope3-users mailing list
Zope3-users@zope.org
http://mail.zope.org/mailman/listinfo/zope3-users


Re: [Zope3-Users] ldappas+ldapadapter

2007-07-17 Thread Sergey Alembekov
On Mon, 16 Jul 2007 04:19:51 +0400
Sergey Alembekov [EMAIL PROTECTED] wrote:

 Hi, everyone!
 
 I'm trying to use ldap based authentification. I successfully installed
 and tested ldapadapter, also i installed ldappas. 
 But when i'm trying to Add LDAP Authentication Plugin in PAU, there is 
 nothing in popup
 menu LDAP Adapter Name. 
find it!
 
* The LDAP Adapter Vocabulary list (used by ldappas) was showing an
  enormous list of irrelevant things. Instead only show those
  LDAPAdapters that were registered. Note: each ldapadapter must be
  registered with a particular *name* for it to show up properly in
  the user interface of ldappas now...


-- 
Regards, Sergey.  
___
Zope3-users mailing list
Zope3-users@zope.org
http://mail.zope.org/mailman/listinfo/zope3-users


[Zope3-Users] Re: View or content provider

2007-07-17 Thread Daniel Nouri
Hermann Himmelbauer wrote:
 Am Dienstag, 17. Juli 2007 14:08 schrieb Stephan Richter:
 On Monday 16 July 2007 19:32, Daniel Nouri wrote:
 I do not recommend using views for content that is only
 used inside a template. Because context/@@viewname
 is also traversable as a real view and will probably show
 up in google.
 How would it show up in Google?  Google bots don't try arbitrary URLs,
 they follow links.

 Using ordinary views for parts of a HTML page works perfectly for me.
 It works at the cost of security. How do you know that noone will figure
 out those views? And how do you know that they are properly secured, if you
 never test them standalone? This might not be too problematic for a single
 project, but would you like to install a package and suddenly get all those
 views that you do not know whether they are properly secured and may reveal
 sensitive information? I can tell you that some of my clients do care about
 this!
 
 I agree with this: Security through obscurity is always a bad idea. In cases 
 where content is not yet ready for the public, it may be o.k. to hide 
 information by unknown URLs, but not on a long-term scale.
 
 You can bet that someone will in some way find out the URL. For instance, I 
 once published a site by sending a code snippet with the URL to the Plone 
 mailing list and Google collected it from the archive (fortunately, no big 
 deal in my case).

You got the wrong idea.  My intention was not to say: No one knows how to
access those views, so they're secure.  But rather: I wouldn't worry about
search engines picking up those (public) snippets of HTML.  The problem here
is that e.g. Google would index parts of pages that should only be seen in
the context of a bigger, complete page.

Regards,
Daniel

___
Zope3-users mailing list
Zope3-users@zope.org
http://mail.zope.org/mailman/listinfo/zope3-users


Re: [Zope3-Users] z3c.zalchemy / z3c.sqlalchemy

2007-07-17 Thread Christian Theune
Am Dienstag, den 17.07.2007, 14:52 +0200 schrieb Andreas Jung:
 
 --On 17. Juli 2007 14:43:27 +0200 Thierry Florac [EMAIL PROTECTED] 
 wrote:
 
 
Hi,
 
  I'm looking for packages to ease integration of SQLAlchemy and Zope3.
  I found the two references listed into this message's subject and was
  wondering if there was any link between then, if both of them are
  up-to-date and actively maintained, and what where the benefits of using
  any or both of them...
 
 z3c.sqlalchemy (written by myself) is actively maintained in will be used
 in several upcoming projects. The goals and usecases covered by 
 z3c.sqlalchemy are documented on the cheeseshop project page. z3c.zalchemy 
 isn't actively maintained as far from what I heard some weeks ago. 
 z3c.zalchemy tries to approach problems I did not have or I did not 
 understand. It's a bit more Zope 3 oriented while z3c.sqlalchemy works
 fine on Zope 2 and Zope 3. To add another choice: collective.lead by
 Martin Aspeli.

I'm using z3c.zalchemy and am happy to fix bugs, so you could call it
maintained by me. I'm not a consumer of the very Zope 3 (read: content)
-oriented approaches, but I am working on some reasonable integration
issues to make the use as transparent as possible in Zope 3.


___
Zope3-users mailing list
Zope3-users@zope.org
http://mail.zope.org/mailman/listinfo/zope3-users


Re: [Zope3-Users] Re: View or content provider

2007-07-17 Thread Stephan Richter
On Tuesday 17 July 2007 14:18, Daniel Nouri wrote:
  Content providers and viewlets are not publically traversable. Being
  traversable does not make them insecure but it offers one more point of
  access and a potential security hole if not reviewed correctly. Do you
  test the security for all those little views?

 You're right.  There's potential security holes there.  However, my feeling
 is that views are well understood and that securing them is trivial.

Uh hu, if you say so. I bet you, you do not even know about half the URLs that 
are available on any given context. Just use APIDOC to discover them.

 Actually, I can think of why securing them individually is actually quite
 useful.  Imagine I register a utility that's a list of view or adapter
 names (for my site's left column).  A rendering view would go over that
 list, see if the views apply by trying to look them up on request and
 context and then check security.  Lastly, it would render the remaining
 items.

Well, that tests if the security is too tight not too loose.

 To each his own.  However, I'm not afraid to roll my own based on CA
 primitives, and others shouldn't be either.

No you should not, but you should be aware of certain things, including 
security. If you do not want to listen to our experiences you do not have to.

Regards,
Stephan
-- 
Stephan Richter
CBU Physics  Chemistry (B.S.) / Tufts Physics (Ph.D. student)
Web2k - Web Software Design, Development and Training
___
Zope3-users mailing list
Zope3-users@zope.org
http://mail.zope.org/mailman/listinfo/zope3-users


[Zope3-Users] Re: View or content provider

2007-07-17 Thread Daniel Nouri
Hi Roger!

Roger Ineichen wrote:
 If you like a explicit pattern, then calling views in ZPT is
 fine. On the other hand, if you use a viewlet manager,
 the manager can implement conditions and show based on
 rules e.g. session state or login status more or less
 viewlets.
 
 I think best reason to use viewlet is, if you need a 
 very flexible conditional concept.

plone.portlets introduces some two dozen (!) interfaces/concepts on top of
viewlets in order to implement the flexibility that it needs.  E.g. it
introduces an 'available' method/property that controls visibility, which
viewlets by themselves lack.  I imagine I could do this with less overhead
without viewlets (see my other mail), or IOW: viewlets don't seem inherently
flexible to me.


Regards,
Daniel

___
Zope3-users mailing list
Zope3-users@zope.org
http://mail.zope.org/mailman/listinfo/zope3-users


Re: [Zope3-Users] Re: View or content provider

2007-07-17 Thread Stephan Richter
On Tuesday 17 July 2007 14:28, Daniel Nouri wrote:
 plone.portlets introduces some two dozen (!) interfaces/concepts on top of
 viewlets in order to implement the flexibility that it needs.  E.g. it
 introduces an 'available' method/property that controls visibility, which
 viewlets by themselves lack.  I imagine I could do this with less overhead
 without viewlets (see my other mail), or IOW: viewlets don't seem
 inherently flexible to me.

Then you do not understand them. They are inherently flexible because content 
providers are multi-adapters of context, request, and view and viewlets are 
multi-adapters of context, request, view, and viewlet manager. Using adapted 
objects as discriminators has opened totally new ways of developing UI 
patterns in Zope 3. We have heavily learned from using those patterns and I 
think the new z3c.form* framework benefitted a lot from it.

As to portlets. When talking about portlets, the Web community refers usually 
to features described in JSR 168. Viewlets have absolutely no ambition to 
come even close to this. In fact, we specifically designed viewlets to do 
much less with the intend to later implement portlets on top of them.

To you viewlets might look extremely simple, in idea and implementation. But 
this did not come over night and we said: Oh cool, let's use a 
triplet-adapter to do content providers. Roger and I did an independent 
implementation of viewlets, then fiercly discussed for nearly a week (people 
attending the Tuebingen sprint can attest to this) the design goals and 
implementation. The simple design of both, content provider and viewlets, is 
thus a result of a deep understanding of UI development problem, not 
something that was thrown together quickly. You know, often less is more!

As to plone.portlets, I think they are heavily overengineered. Last time I 
looked at its API, it was heavily bloated. This might be a result of being a 
Plone package though, I do not know, but I would certainly implement them 
much slimmer. 

Regards,
Stephan
-- 
Stephan Richter
CBU Physics  Chemistry (B.S.) / Tufts Physics (Ph.D. student)
Web2k - Web Software Design, Development and Training
___
Zope3-users mailing list
Zope3-users@zope.org
http://mail.zope.org/mailman/listinfo/zope3-users


[Zope3-Users] Zope 3 API documentation needs a new strategy

2007-07-17 Thread Luciano Ramalho

One of the first questions anyone needs answered when studying a new
framework is Where is the canonical reference for the API?.

If you google for zope 3 api documentation the first link is Stephan
Richter's mail of Jan/2004 announcing API doc. In it, there is the
link:

http://localhost:8080/++apidoc++

However, that URL is not active by default, and it takes some research
discover how to make it work.

The second link returned by Google is this:

http://wiki.zope.org/zope3/Documentation

Here we find vague references to a certain API Doc Tool, but no
explanation of how to enable it and access it (OK, that is a Wiki, so
it's easy to fix; I'll start the APIDocTool page).

The remaining links returned by Google are even less helpful, and on
page 2 we get a link to Shane Hathaway's post titled Zope 3
Frustration...

Everyone expects the API documentation for a framework to be highly
visibile in it's main web site.

OK, I understand Zope 3 is undergoing a radical reorganization right
now, which is a further push to descentralization, making the idea of
locally generated API documentation even more attractive.

But I think we *also* need the API published on Zope.org, for a few
advantages that the apidoc tool will never be able to give us:

- we need to be able to use Google to search the API documentation
(even if the apidoc search worked perfectly, which it doesn't)

- we need to be able to collaborate with comments and examples to the docs;

The second point is really crucial. Just take a look at this page, *please*:

http://www.php.net/manual/en/ref.classobj.php

Last year I had to do a project in PHP, and again and again the
answers I was looking for were in the contributed comments and
examples, even though their documentation is very compreehensive. The
same amazing user participation can be seen in all 23 languages (!) in
which the PHP API is documented.

Contributing to Zope 3 docs must be made *much* easier than being a
Zope 3 committer.

Cheers,

Luciano
___
Zope3-users mailing list
Zope3-users@zope.org
http://mail.zope.org/mailman/listinfo/zope3-users