forrest-svn mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cross...@apache.org
Subject svn commit: rev 30708 - in forrest/trunk: etc src/documentation/content/xdocs/docs
Date Mon, 26 Jul 2004 05:41:32 GMT
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>

Mime
View raw message