Upgraded HiveMind to Forrest 0.6

The Forrest team recently announced Forrest 0.6. When I first switched HiveMind away from Maven, a key concern was documentation, and Forrest provides much more and better functionality than Maven.

However, like Maven, with Forrest you venture forth from the narrow blessed path at your own risk. I had much trouble getting HiveMind's documentation to build to my liking under Forrest. The tool is complex, with many, many, moving parts (including Cocoon !) and will often create wrong output, rather than report an error.

In 0.5, I discovered that I had to include <index href="index.html"/> in my site.xml file to get the tabbed navigation views to work properly.

The upgrade to 0.6 is supposed to be simple but I found a number of problems:

• The imported Ant script doesn't work (details in the forrest-user mailing list). Even if it did, it would pollute my project with many additional targets. My workaround was to re-invoke Ant using the patch Ant libraries shipped with Forrest (!)
• Had to completely rebuild the skinconf.xml file
• cli.xconf had to be changed, and it was necessary to create a project.configfile entry in my forrest.properties file
• Forrest 0.6 kept emitting the exact same file as index.html at each level of my project. This was not only the wrong information for the hivemind, hivemind-lib and hivemind-examples folders, but didn't render because relative paths to the style sheets were broken. The only workaround I found, and this is very ugly, is to change all the document hrefs in my site.xml to use complete paths to each file (i.e., <index href="hivemind/index.html"/>).
• I've been getting various errors related to wholesite.html and wholesite.pdf, so I turned that off.

All told, I spent quite a few hours getting this working to this level, most of it the kind of blind thrashing that's necessary when tools don't validate properly, or report problems usefully. Many times I strongly considered working backwards to Forrest 0.5.

The results so far are a cut above what we had before. The smaller fonts are good (as is the JavaScript based font-size control). There are a number of layout glitches (at least under FireFox) related to long entries in the left-side menu. I with I had more control over what menu items start expanded (maybe I do have that, but Forrest documentation is paradoxically pretty poor and I've yet to find it).

Forrest 0.6 also gives you more control over style, by making it easy to integrate some custom CSS styles into the default stylesheet (this is part of skinconf.xml) and allowing all elements to accept a class attribute.

Overall, I'd give Forrest a C+ as a grade; the final results once working are a good B+/A- ... but the process for getting there (especially when factoring in the pain of an upgrade) has to be considered. The cost of adoption can be extraordinarily high, especially if you have an existing project and existing documentation.

Fortunately, unlike the Maven team, the Forrest team recognizes this at least as far as their version numbers; 0.6 indicates that it is still an alpha or beta release and they know they have some distance to go before they can call it a true product.