Return-Path: 
 <cocoon-dev-return-34471-apmail-xml-cocoon-dev-archive=xml.apache.org@xml.apache.org>
Delivered-To: apmail-xml-cocoon-dev-archive@xml.apache.org
Received: (qmail 11262 invoked by uid 500); 24 Dec 2002 05:48:27 -0000
Mailing-List: contact cocoon-dev-help@xml.apache.org; run by ezmlm
Precedence: bulk
list-help: <mailto:cocoon-dev-help@xml.apache.org>
list-unsubscribe: <mailto:cocoon-dev-unsubscribe@xml.apache.org>
list-post: <mailto:cocoon-dev@xml.apache.org>
Reply-To: cocoon-dev@xml.apache.org
Delivered-To: mailing list cocoon-dev@xml.apache.org
Received: (qmail 11251 invoked from network); 24 Dec 2002 05:48:26 -0000
Subject: Re: Javadocs: need basic package information
From: David Crossley <crossley@indexgeo.com.au>
To: cocoon-dev@xml.apache.org
In-Reply-To: <3E06DF53.1000708@a1.net>
References: <3E06DF53.1000708@a1.net>
Content-Type: text/plain
Content-Transfer-Encoding: 7bit
X-Mailer: Ximian Evolution 1.0.3 (1.0.3-6) 
Date: 24 Dec 2002 16:48:34 +1100
Message-Id: <1040708915.8768.450.camel@ighp>
Mime-Version: 1.0
X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N

Bernhard Huber wrote:
> hi,
> i have read the thread 
> http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=102056702426129
> again.
> 
> i'd like to start it,
> 
> i think writing a single packages.xml is better than
> maintaining 84 package.html files.

Great. This is a good approach.

> * add a packages.dtd ala faq.dtd

Yes, it is good to constrain the content.
How much constraint is suitable? Perhaps faq.dtd
is too loose, e.g. it allows <table> ...
On the other hand, perhaps we should not try to
pre-determine the content model. 

> * write a single packages.xml conforming to packages.dtd
> * write for each package :
>    1st paragraph headline, abstract will be presented in
>   right column of the package list

I presume that only plain text is allowed in this element.

Perhaps it should be a <headline> element, rather than <p>.

>    2nd paragraph usage of classes, interfaces, exceptions
>    of this package
>    following content links to more specs, and docs

Needs a container element - your example rightly has more
than one paragraph. How about <description> ?

> * write a xslt to transform, and split packages.xml to the src/java 
> subdirectories
> *  do the same for blocks, each block will have its own packages.xml
> * add a packages2html.xsl to the cocoon documentation
> 
> do we have specs documents? there is specification.dtd, but is
> there any use ?

I am not sure what you mean by "specs documents", and i have
never understood what this DTD was intended for.
--David

> any comments?
> by bernhard
> 
> 
> packages.xml snippet for org.apache.cocoon:
> 
> <?xml version="1.0" ?>
> <packages>
> <!-- package missing -->
> <package name="java/org/apache/cocoon">
> <p>
>    Provides interfaces, classes, and exceptions of Cocoon's processor.
> </p>
> <p>
>    The Cocoon processor is the top-level controller of the Cocoon system.
>    The interface Processor defines the basic contract of the Cocoon 
> processor.
>    The class Cocoon implements the Processor interface.
> </p>
> <p>
>    The Cocoon processor is an Avalon component, processing an 
> Environment object.
>    The Environment is created in a concrete runtime environment, like
>    Servlet environment, and Commandline environment.
> </p>
> <since version="Cocoon 2.0"/>
> </package>
> 
> <!-- package missing -->
> <package name="java/org/apache/cocoon/acting">
> <p>
>    Provides interfaces, classes of Cocoon's action component.
> </p>
> <p>
>    The Cocoon action is an Avalon component.
>    A Cocoon action defines an hook-up for defining a pre sitemap 
> pipeline processing.
> </p>
> <since version="Cocoon 2.0"/>
> </package>
> <!-- more packages
> ...
> -->
> </packages>



---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org