> From: Leo Simons [mailto:[EMAIL PROTECTED]] > > > Motivation > ---------- > Our current documentation build process is a pain in the *** > to use. Cocoon is a little bit of overkill. It takes about 30 > minutes on my machine to generate all our docs. This needs to change.
I feel your pain. There have been improvements I believe, but I haven't integrated them yet. > It would also be nice to add some auto-generated > documentation to our website (jdepend, javasrc, etc). The new > tools handle some of this now, and will handle more of it as > they mature. Absolutely. I am getting ready to do a comparison between the Maven and Centipede to see how easy it is to #1 start a new project, and #2 merge into an existing project. Both of them need some fine-tuning on the directory hierarchy. > > 'Standards' concern > ------------------- > It would be somewhat annoying to adopt one option now, then > find it has all but died in a few months time because it lost > out to a competing tool, if this would mean a lot of work to > move from one tool to the other. With my understanding between the two, migration would not be that difficult--the main thing is the project descriptor. The tough migration is going from what we have now to one of the others. > Smooth migration concern > ------------------------ > We have an extensive, and in some cases also quite complex > build system in place, that we should not break. Fortunately, > use of ant and antcall means this is easy enough to do. We do, and this is something we should try to get Maven and Centipede to handle. I do like Centipede's design. Everything is deferred to "cents" which are build components. Those components handle everything from documentation building to project hierarchy building. > Dog food concern > ---------------- > We currently use cocoon, which is built on top of several > avalon components. It would be nice to keep using cocoon as > it means we show the world we like our own dog food. :) I will report on Centipede as it uses that. > Features concern > ---------------- > We don't want to loose any of our current documentation > features. It would be especially cumbersome if we would have > to modify our xdocs directories. > > New features would also be cool. Absolutely. > Ease-of-use concern > ------------------- > We currently include a forked ant in the jakarta-avalon cvs > module because it makes it a little easier for users to get > started (they don't have to install ant first). We should > either include the new tools in jakarta-avalon cvs as well > (to keep everything just as easy to use), or we need to > accept the extra installation chores for people getting > started with our project. If we choose either solution, we should do the extra install step. > Option: maven > ------------- > standard: maven is not any kind of standard yet. Some people > (mainly Jon > Stevens) believe it will be the new standard for jakarta site > generation in the future. > migration: maven is isolated from the rest of the build > process through the use of external ant build files. > stability: maven is in third beta and its API will probably > not change very much. dog food: maven does not provide > support for cocoon. > features: maven does not provide support for having the xdocs > <title> tag somewhere in the body of the page by default. It > also does not provide support for our chosen skin atm. new > features: project info generation, dependency information (on > a .jar level), look-and-feel similar to Scarab (which will > replace BugZilla sometime in the future), junit reports, > jdepend reports, checkstyle reports, javadocs, src xref > (javasrc) ease of use: maven does not promote inclusion in > CVS, though it should be possible. The extra docs that Maven includes are quite helpful. However, it would also be relatively easy to do the same with Centipede. Scarab is a great tool for bugtracking, but I am not convinced it is so hot for project look and feel. It does not address navigation issues as nicely as I would want. One thing that it does not deal with very well at all is a breadcrumb trail. Centipede uses Cocoon, which should have something in it that handles the breadcrumb trail for us. > Option: Centipede w/ Forrest > ---------------------------- > standard: Forrest will be the standard for the xml project > site. It uses XSLT, also a standard. > migration: centipede is isolated from the rest of the build > process through the use of external ant build files. > stability: centipede is in its first beta. The most important > part of its API that we see is borrowed from Forrest, and > thus Cocoon, which we already use. dog food: Centipede & > Forrest make use of cocoon. > features: no problems. > new features: all maven's features through a maven module, > jdepend, junit reports, javasrc, pluggable look and feel, > pluggable modules (support for UML generation etc will be > added) ease of use: Centipede and Forrest can be included in > CVS like the current tools we use. Which I am not sure should be necessary. > Quality of Analysis > ------------------- > This analysis is based on browsing of the maven and centipede > project websites, following of discussion of these tools, and > limited use of both projects. There are probably quite a few > flaws in it. I think it will suffice for making a decision, though. I will have a more detailed analysis in a bit. I am doing a new project comparison for the two. My biggest interest is in error feedback when something is not quite right. > Proposals > --------- > - Put the latest Centipede beta (which includes useful stuff like > Forrest) in jakarta-avalon cvs, and start generation of our > website using it. > > - Add new features to the website (jdepend, junit, etc) > offered by Centipede incrementally. > > - Slowly migrate parts of our build process to be managed by > Centipede, where this is possible. Let's wait until I perform my analysis between the two on default install. Centipede *does* support our skin BTW. -- To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
