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: [EMAIL PROTECTED] For additional commands, email: [EMAIL PROTECTED]
