cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Sylvain Wallez <sylvain.wal...@anyware-tech.com>
Subject Re: Javadocs: need basic package information
Date Fri, 03 Jan 2003 09:44:23 GMT
David Crossley wrote:

>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.
>  
>

Their age doesn't mean they're obsolete. Even more considering the large 
amount of information they contain ;-)

>>- 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.
>

Can you elaborate more on this ? As far as I understand them (they're 
still fuzzy), blocks will provide some sitemap-level services 
implemented using block-specific libraries that won't be visible from 
outside the block.

How does this relate to javadoc ?

>>>* 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.
>

Do you mean generating all package.html from a single package.xml and 
then aggregating back all the individual package.html in a single doc ? 
I don't follow you here...

Sylvain

-- 
Sylvain Wallez                                  Anyware Technologies
http://www.apache.org/~sylvain           http://www.anyware-tech.com
{ XML, Java, Cocoon, OpenSource }*{ Training, Consulting, Projects }



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


Mime
View raw message