Apache Software Foundation > Apache Forrest
Font size:      

Our Contract

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.