<?xml version="1.0"?>
<!--
  Copyright 2002-2004 The Apache Software Foundation

  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://apache.org/forrest/dtd/document-v12.dtd">
<document> 
  <header> 
    <title>Our Contract</title> 
    <notice>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
      <link href="site:mail-lists">mail list</link> know if
      any of the bullets listed here are out of sync with the real
      implementation.</notice>
    <abstract>This document describes in a very techy bullet-style way how to use Forrest.</abstract> 
  </header> 
  <body> 
    <p>This document describes the formal contract between the
      <strong>Forrest distribution code</strong>, hereafter referred as Forrest, and
      the <strong>Project (team) using it for generating its documentation
      web-site</strong>, hereafter TheProject, or in the best case: You.</p><section> 
      <title>Forrest will:</title> 
      <ul> 
        <li>provide DTDs, skins, cocoon-pipelines, and a willing team of
          supporting developers at the forrest-dev
          <link href="site:mail-lists">mail list</link></li>
      <li>use Cocoon to generate the HTML and PDF documentation for TheProject</li> 
      </ul> 
    </section> 
    <section> 
      <title>TheProject Must:</title> 
      <note><code>{docroot}</code> is the location inside TheProject's file
        hierarchy where all documentation related resources are stored. Commonly,
        <code>{docroot}</code> equals to
        <code>{projecthome}/src/documentation</code></note> 
      <ul> 
        <li>provide XML content in <code>{docroot}/content/xdocs</code>
          according to the forrest DTDs,</li> 
        <li>provide content navigation metadata by adding
          <code>site.xml</code> and <code>tabs.xml</code> files in there as
          well.</li>
      <li>provide own xml project descriptor files in the directory <code>{projecthome}</code></li></ul> 
    </section> 
    <section> 
      <title>TheProject Can:</title> 
      <ul> 
        <li>provide its own skin in a directory
          <code>{docroot}/skins/{your-skin-name}</code> (check the current Forrest skins
          and the related pipelines to see what they are doing)</li> 
        <li>provide own DTDs (and stylesheets) to work with in
          <code>{docroot}/resources/schema/dtd</code> 
          <ul> 
            <li>maybe also extra required stylesheets to convert own grammar to
              'document' (being the format that the skins work on)</li> 
            <li>and probably with an updated
              <code>{docroot}/resources/schema/catalog</code></li> 
          </ul> </li> 
        <li>provide its own overwriting versions of
          <code>{docroot}/sitemap.xmap</code> (and other *.xmap files),
          <code>{docroot}/cocoon.xconf</code> etc
          ... (be sure you know what you are doing since you're leaving the area where
          other Forresters can help you out.</li> 
      </ul> 
    </section> 
  </body>
</document>
