cocoon-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Daniel Barclay <Daniel.Barc...@digitalfocus.com>
Subject Re: ldap processor; better documentation needed
Date Mon, 10 Apr 2000 21:09:08 GMT
Stefano Mazzocchi wrote:
> 
> schenck@posc.org wrote:
> >
> > Laura,
> >
> > You need to install Sun's JNDI package.  The docs are not clear on this.
> 
> >From the FAQ:
> 
> <faq>
>  <question>Why the LDAP processor doesn't work?</question>
>  <answer>
>   <p>Make sure you have the <link
> href="http://java.sun.com/products/jndi/index.html">Sun JNDI API</link>
>    package installed in your classpath.</p>
>  </answer>
> </faq>
> 
> Please, tell me how to make this better, because I honestly don't
> know...

What's wrong with putting that information in the LDAP Processor 
documentation?  

(If something is a frequently asked question, it usually means that some 
other documentation is deficient.)

Assuming that docs/ldap.html in the Cocoon distribution is the main
documentation, it seems that specifying the requirement for the JNDI
package would fit; that page does have a "Installation" section.


By the way, is docs/ldap.html in the Cocoon distribution the primary user
documentation for the LDAP processor?  If so, it needs some work.


Although it gives examples, it never specifies many of the elements and
attributes.  For example, it doesn't specify:

- whether element type "ldap-defs" has any attributes
- whether multiple ldap-defs elements are allowed and what their combined
  semantics are
- whether anything other than ldap-server and querydefs elements can 
  appear in the ldap-defs element
- whether multiple ldap-server elements can appear in the ldap-def element

- the meaning of the "name" attribute of an ldap-server element
- the meaning of the content of an initializer element, etc.
- the meaning of the "server" and "connection" attributes of
  ldap-query elements (e.g., what is the difference?)

- the full set of attributes of element type ldap-query 


At one point, the page says: "a partial list of attributes is:  ..."
Well, where is the full documentation?


***
Why not have a (partial) DTD (with comments or other annotation that
specifies the meaning of the elements, attributes, content, and structure)?



The page also has some terminology errors:
- It refers to "node" many times when it should be "element" (the page is
  talking about XML, not DOM, XPath, or XSLT data.)
- It also refers to "tag" many times when it should also be "element".

(Also, a few typos: "defitions"; "A ldap-defs..." ("An ldap-defs...").)



Daniel
-- 
Daniel Barclay
Digital Focus
Daniel.Barclay@digitalfocus.com

Mime
View raw message