cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Crossley <cross...@indexgeo.com.au>
Subject Re: Javadocs: need basic package information
Date Fri, 03 Jan 2003 07:31:39 GMT
Sylvain Wallez wrote:
>Bernhard Huber wrote:
<snip/>
>> i think writing a single packages.xml is better than maintaing
>> 84 package.html files.
> 
> IMO, a centralized XML file may not be better as far as keeping
> it up to date is concerned :
> - people may often forget to update a central file far away
> from the source files.

No-one is adding package.html files next to the source
at the moment anyway. There are only 9 such files under
src/java and they are mostly over six months old.

> - will people really go inside a large XML file containing 89
> toplevel 
> elements to update a single package description ? I think no.

If they have the motivation to describe something, then
the type of file should not stop them. Yes, editing and
navigating a large file may become a problem.

There is one important reason for having separate
package.xml next to the component source code ... when
Cocoon is able to add new components (blocks?) automatically.

>> * add a packages.dtd ala faq.dtd
>
> I don't like neither constraining the content : package.html,
> as its name states, accepts any html markup. Javadoc extracts
> the first sentence to build the package summary table, but the
> file can contain a detailed design description of the package,
> including tables, images, etc. Sure, we don't have such
> detailed package.html now, but 
> constraining the content will definitely prevent it...
<snip/>

I think that the package.xml does need to be well-structured.
This enables us to also extract information to be aggregated
into other documents, like a table of all components since
the 2.1 version.

Bernhard's proposal to use something like faq.dtd does allow
sufficient detailed description (i.e. tables, images).

Each individual package.html for javadocs consumption can be
generated from package.xml at build-time. And if a single
document of all packages is needed then that can be aggregated
from the individual docs.

--David



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


Mime
View raw message