You are viewing a plain text version of this content. The canonical link for it is here.
Posted to svn@forrest.apache.org by cr...@apache.org on 2004/07/26 07:41:32 UTC
svn commit: rev 30708 - in forrest/trunk: etc src/documentation/content/xdocs/docs
Author: crossley
Date: Sun Jul 25 22:41:32 2004
New Revision: 30708
Modified:
forrest/trunk/etc/docs-review.txt
forrest/trunk/src/documentation/content/xdocs/docs/forrest-contract.xml
Log:
Done minor review of forrest-contract.xml
Modified: forrest/trunk/etc/docs-review.txt
==============================================================================
--- forrest/trunk/etc/docs-review.txt (original)
+++ forrest/trunk/etc/docs-review.txt Sun Jul 25 22:41:32 2004
@@ -15,7 +15,7 @@
| |-- document-v12.xml
U | |-- dreams.xml
F | |-- dtd-docs.xml
- | |-- forrest-contract.xml
+R | |-- forrest-contract.xml
| |-- forrestbar.xml
F | |-- forrestbot-web-interface.xml
F | |-- forrestbot.xml
Modified: forrest/trunk/src/documentation/content/xdocs/docs/forrest-contract.xml
==============================================================================
--- forrest/trunk/src/documentation/content/xdocs/docs/forrest-contract.xml (original)
+++ forrest/trunk/src/documentation/content/xdocs/docs/forrest-contract.xml Sun Jul 25 22:41:32 2004
@@ -14,7 +14,7 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
-<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://forrest.apache.org/dtd/document-v12.dtd">
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.3//EN" "http://forrest.apache.org/dtd/document-v13.dtd">
<document>
<header>
<title>Our Contract</title>
@@ -26,54 +26,78 @@
<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>
+ <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>
+ <note>
+ This document describes the formal contract between the
+ <strong>Forrest distribution code</strong>, hereafter referred as
+ "Forrest", and
+ the <strong>Project (team)</strong> that is using it for generating
+ its documentation and web-site, hereafter referred to as "TheProject".
+ </note>
+ <note>
+ Some terminology will assist: <code>{docroot}</code> is the location
+ inside TheProject's file hierarchy where all documentation related
+ resources are stored. Usually <code>{docroot}</code> equals to
+ <code>{projecthome}/src/documentation</code>
+ </note>
+
+ <section id="forrest-will">
<title>Forrest will:</title>
+ <p>Provide infrastructure ...</p>
<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>
+ <li>Provide document type definitions (DTDs), skins, default sitemaps,
+ Cocoon pipelines.
+ </li>
+ <li>Provide 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 id="project-must">
+ <title>TheProject must:</title>
+ <p>Provide content and configuration ...</p>
<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>
+ <li>Provide XML content in <code>{docroot}/content/xdocs</code>
+ according to the Forrest DTDs or one of the other input formats.
+ </li>
+ <li>Provide navigation metadata using the configuration files
+ <code>site.xml</code> and <code>tabs.xml</code>
+ </li>
+ <li>Provide the skin configuation file in
+ <code>{projecthome}/skinconf.xml</code>
+ </li>
+ </ul>
</section>
- <section>
- <title>TheProject Can:</title>
+
+ <section id="project-can">
+ <title>TheProject can:</title>
+ <p>Add extra abilities ...</p>
<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
+ <li>Provide its own skin in
+ <code>{docroot}/skins/{your-skin-name}</code> (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.)</li>
+ <li>Provide own DTDs to handle other specialised document types 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>
+ <li>and extra stylesheets to convert own grammar to the
+ intermediate 'document' structure.</li>
+ <li>and declare those extra DTDs in
+ <code>{docroot}/resources/schema/catalog.xcat</code></li>
+ </ul>
+ </li>
+ <li>Provide its own overwriting versions of sitemaps
+ (<code>{docroot}/sitemap.xmap</code> and other *.xmap files)
+ ... (be sure you know what you are doing since you are then leaving
+ the area where other Forresters can help you out.
+ </li>
</ul>
</section>
</body>