Our Contract

Our Contract The legal tone of this document is just a gimmick, this is not a legal document in any sense. At all times: since this is open source: the real contract is described in the implementation details of the full distribution. This tries to list (not explain) what the ins and outs of using Forrest is about. Please let the forrest-dev mail list know if any of the bullets listed here are out of sync with the real implementation. This document describes, in a very techy bullet-style way, how to use Apache Forrest.

This document describes the formal contract between Apache Forrest and the Project (your development team) that is using it for generating its documentation, hereafter referred to as "TheProject". Some terminology will assist: {docroot} is the location inside TheProject's file hierarchy where all documentation related resources are stored. Usually {docroot} equals to {projecthome}/src/documentation

Apache Forrest will:

Provide infrastructure ...

Use Apache Cocoon to generate the HTML and PDF documentation for TheProject.
Provide default Cocoon sitemaps, Cocoon pipelines, skins and other theme abilities, document type definitions (DTDs) and other appropriate schema.
Provide a framework for plugins and various input/output capabilities as plugins.
Provide a willing group of supporting developers at the mail lists.

TheProject must:

Provide content and configuration ...

Provide XML content in {docroot}/content/xdocs according to the Forrest DTDs, or one of the other input formats.
Provide navigation metadata using the configuration files site.xml and tabs.xml
Provide the skin configuation file in {docroot}/skinconf.xml

TheProject can:

Add extra abilities ...

Specify other properties (e.g. additional plugins) in {docroot}/forrest.properties
Provide its own skin in {docroot}/skins/{your-skin-name} (Check the current Forrest skins and the related pipelines to see what they are doing. Bear in mind that the provided skins are able to be configured and may already meet your needs.)
Provide own DTDs to handle other specialised document types in {docroot}/resources/schema/dtd
- and extra stylesheets to convert own grammar to the intermediate 'document' structure.
- and declare those extra DTDs in {docroot}/resources/schema/catalog.xcat
Provide its own overwriting versions of sitemaps ({docroot}/sitemap.xmap and other *.xmap files) ... (be sure you know what you are doing since you are then leaving the area where other people can help you out.
Develop its own additional functionality using plugins.