Intro

Maven is a nice tool. For those who want more feature-rich documentation generation than it offers and a rigid documentation format, with the potential to easily scale up to a realtime webapp, it makes sense to extend it with forrest. With the new forrest plugin, this is now easy to do.

Install and usage

Installing the plugin

dead easy!

1) install maven-beta-9 or later, if you don't have it yet 2) install the plugin  wget http://lsd.student.utwente.nl/repository/forrest/jars/maven-forrest-plugin-1.1.jar $MAVEN_HOME/plugins/ 

Using the plugin

just as easy!

1) convert your maven-format docs to document-v11 format. Keep them in src/xdocs/ 2) optional: add a forrest.properties file to your project to customize any forrest settings, if you want 3) use the 'forrest:generate' goal {{{ cd $MY_PROJECT

• maven forrest:generate }}}

or add

{{{ <postGoal name="xdoc">

• <attainGoal name="forrest:generate"/>

• </postGoal> }}}

to your project's maven.xml, so you can resume documentation generation as normal using 'maven xdoc' and friends.

Building the plugin yourself

1) checkout xml-forrest module {{{ mkdir ~/cvs/

• cd ~/cvs/

  cvs -d anoncvs@cvs.apache.org:/home/cvspublic checkout xml-forrest }}}

2) get plugin patch {{{ wget http://cvs.apache.org/~leosimons/maven-forrest-plugin-20030610.zip /tmp

• mv /tmp/maven-forrest-plugin* ~/cvs/xml-forrest/src/resources cd ~/cvs/xml-forrest/src/resources rm -Rf maven-plugin unzip /tmp/maven-forrest-plugin-20030610.zip }}}

3) build and install the plugin {{{ cd maven-plugin

• maven plugin # this is a target inside the maven-plugin-plugin, atm
  • # it just calls the jar:jar goal/target
  maven plugin:install # this is another target inside that plugin;
  • # it just copies the generated jarfile into your local # maven installation }}}

Example usage

1) install plugin as above 2) checkout avalon and avalon-excalibur modules {{{ mkdir ~/cvs/

• cd ~/cvs/

  cvs -d anoncvs@cvs.apache.org:/home/cvspublic checkout avalon avalon-excalibur cd ~/cvs/avalon-excalibur/compatibility }}}

3) build excalibur-compatibility documentation using maven and forrest  maven xdoc 

4) view the generated docs in ~/cvs/avalon-excalibur/compatibility/target/docs

Things To Do

Devs wanted!

It should be pretty clear what it does (even if you don't know maven or jelly, like me ;), basically the shbat distribution is generated, patched, then jarred up along with some minimal script files. The most tricky bit atm is figuring out how to get the oodles of required jars on the proper classpaths. Which I seem to have succeeded in

- add plugin to forrest cvs

- figure out how to neatly replace the xdoc generation (right now the forrest:generate target just overwrites any maven-generated files which are in the way)

this is the most tricky part. A symbiotic relationship between maven and forrest can exist to some extent, as you can have maven-generated files easily reference files which will be generated later by forrest, and vice versa (where I believe filterlinks.xsl should be modified in forrest to not overwrite any stuff we know maven will generate).

(I built a patch for that but its not operational yet.)

I saw an anakia2document.xsl sheet and some auxillary files. How easy would it be to detect whether a given xdoc file is in maven's format and have forrest run this automatically? Where does one configure forrest to do that? Is there docs on how to do that (I have a hunch there is some kind of fancy dynamism in some kind of sitemap :D)?

I took a look at how to do this and gave up rather quickly. The mutual dislike between me and XSL is growing rapidly!

- customize forrest skins to include a reference to the maven-generated project reports if they exist    my current thinking is that for now a "reports" tab should be added to a temporary tabs.xml file based on a test for existence of the maven-reports.html file. Is that workable? Where would that test go; how easy is it to modify the tabs.xml file conditionally like that?

I had a look at tabutils.xsl, tab2menu.xsl, etc. Can't figure out how to do this. I think that all that needs to happen is to append

 <div><a href="maven-reports.html">Reports</a></div> 

somewhere in some way. How do you guys make sense out of the multitude of XSL sheets? Is there some editor that makes it workable?

- write a project.xml (maven POM) -> status.xml (Forrest status file) converter

- write a navigation.xml (maven site layout -> sitemap.xmap (Forrest site layout) converter

cheers! - Leo