Upgrading to Apache Forrest 0.9
- New Features
- Java 1.5 (or newer) is required
- Notes about Cocoon version
- Missing project symbols file in some projects
- Improved PDF output plugin
- Improved generated IDs for sections
- Notes about documentation
- General upgrade tips
- Remove project sitemap if not necessary
- To be continued...
This page describes some changes to Apache Forrest that affect people who are upgrading to the 0.9 version. If you have other issues, then please discuss on either the dev or user mailing lists. As more experience is gained, this document will be updated.
(If you are upgrading from a version prior to 0.8 then you will need to see the notes for the previous upgrade.)
The following list shows some of the key new features. See also the RELEASE-NOTES document that was provided with the release package. For the full list of changes, see the main change log and also for each plugin.
- Our packaged Apache Cocoon is upgraded, along with various other important supporting products such as Apache Xerces and Apache Xalan, etc.
- The properties are supplemented by the new Properties system.
- Java 1.5
Some new initial plugins are in the "whiteboard". See the entries in the change log and see each plugin's documentation and changes log. This includes the new Dispatcher. See Status of Themes: Skins and Dispatcher.
Java 1.5 (or newer) is required
Java 1.5 (or newer) is required, starting with this Forrest 0.9 version. For further information, see FAQ.
Notes about Cocoon version
Our packaged version of Apache Cocoon has been upgraded to use the latest version of their stable 2.1 branch. This is a major step forward for Forrest. It enables us to use a reliable and up-to-date Cocoon. Forrest developers can again participate at Cocoon to fix issues or develop new blocks. A number of major performance issues are already fixed in this version.
In previous versions of Forrest we were using a development version of Cocoon trunk (i.e. 2.2). A number of things happened which caused us to fall out of synchronisation with Cocoon. They started using Maven as a build system, which took a long time to settle down. In turn that meant that Apache Gump could not perform continuous integration, which shut Forrest off. At the same time Cocoon trunk was making technical advances which changed some of the ways that Forrest interacts with Cocoon. In particular the command-line interface which Forrest uses to build a complete static site. See other notes via FOR-1017.
Cocoon-2.1 is closer to our stalled version of Cocoon-2.2 than the current head of Cocoon-2.2 trunk.
Note that this move does not preclude us from future updates to other versions of Cocoon or even to another xml processing framework.
If you want to use your own version of Cocoon-2.1, for example to add another Cocoon Block or to enhance a particular existing block, then see the notes in the $FORREST_HOME/etc/cocoon_upgrade directory.
Cocoon upgrade issues
There are only two minor issues for those upgrading from the previous version of Forrest:
When you first use this in your existing projects, there will probably be a message about a certain cache item. On the second run all is well. A way to avoid that would be to do 'forrest clean-work' in each of your projects to remove the old Cocoon cache.
The configuration file is now at main/webapp/WEB-INF/cocoon.xconf
Our previous version of Cocoon had a facility called "Running modes" which enabled one set of a minimal group of properties for development and a different set for production. This is not available in Cocoon-2.1 version. If you were using this feature, then simply move your defined properties into the main/webapp/WEB-INF/properties/core.properties file.
Missing project symbols file in some projects
Users of 0.8, and developers with older 0.9-dev, who based their sites on 'forrest seed-basic' rather than 'forrest seed-sample' will be affected by FOR-1075. There was a partially implemented xml catalog with missing symbols file.
You would get the message:
Failed to create InputSource (java.io.FileNotFoundException: .../src/documentation/resources/schema/symbols-project-v10.ent (No such file or directory)...
This is just a warning message from the misconfigured xml entity catalog. To silence it, simply copy the file from a new "seed-basic" site, or more directly by cp $FORREST_HOME/main/fresh-site/src/documentation/resources/schema/symbols-project-v10.ent $PROJECT/src/documentation/resources/schema/symbols-project-v10.ent
This "project symbols" ability using xml entities is useful in two ways. To provide common symbols, words, and phrases, in your source documents (added in v0.8 - FAQ). To configure some Cocoon sitemap components (added in v0.9 - FAQ).
Improved PDF output plugin
In particular, the PDF output plugin has many improvements, uses a newer Apache FOP etc. It is much more configurable, See its plugin documentation.
However there is a minor, but annoying, problem. See FOR-1077. Forrest (via Cocoon) re-generates every document. Every PDF now gets differences due to some internal metadata dates, even though its content might not have changed. When the documentation set is deployed, e.g. via svn, these changed files will also be deployed.
For the Forrest project website, we decided to stop (via skinconf.xml) using PDFs for every page and do it only for some specific documents.
Remember that if you need to use an old version of any plugin, then it can be specified in forrest.properties by appending the version number (e.g. "-0.2" or "-0.3") to the required plugin name.
Improved generated IDs for sections
The conversion of xdoc sections to html will generate named anchors for use with URI fragment identifiers.
Forrest utilises the @id attribute if it exists (ideal). Otherwise it generates one utilising the "section/title" element.
With prior versions of Forrest, an extra automatic ID was always generated. This now only happens if those other pieces are missing.
So when you first update your project's deployed html documentation, there will be many changes removing those old superfluous named anchors (e.g. <a name="N1000E").
Notes about documentation
After each release, the "Versioned Docs" are copied to form the new "dev" set. Ideally the docs are then upgraded in readiness for the new release. This has not been completed for recent releases. In particular there are example snippets of sitemaps which have not yet been upgraded to reflect the changes to the sitemaps and the separation of some core stuff into plugins. See issues FOR-546 and FOR-922 and others.
General upgrade tips
Compare your configuration with that of a fresh seed site.
For example, synchronise your project's skinconf.xml and forrest.properties files:
Take advantage of the separation of concerns. In a new workspace, create a fresh 'forrest seed' site, then tweak its forrest.properties and skinconf.xml until it reflects your old site. When it is ready, replace your project's skinconf.xml and forrest.properties files.
Other configuration should also be synchronised. For example, a project Catalog Entity Resolver or symbols entities (see notes).
Any remaining issues should concern other aspects of your configuration, such as site.xml and your actual content.
Remove project sitemap if not necessary
It has come to our attention that some people have a project sitemap even though they are not using it. Such un-necessary sitemaps should be removed to avoid maintenance issues.
If you do use a project sitemap, then pay attention to the 0.8 upgrade instructions "Forrest configuration simplification".
To be continued...
...as more issues are discovered/remembered :) Please send feedback to the mailing list.