forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cross...@apache.org
Subject cvs commit: xml-forrest/src/documentation/content/xdocs your-project.xml book.xml faq.xml forrest-contract.xml forrestbot.xml
Date Sun, 18 Aug 2002 07:44:57 GMT
crossley    2002/08/18 00:44:56

  Modified:    .        status.xml
               src/documentation/content/xdocs book.xml faq.xml
                        forrest-contract.xml forrestbot.xml
  Added:       src/documentation/content/xdocs your-project.xml
  Log:
  New document for getting started with using Forrest.
  
  Revision  Changes    Path
  1.11      +4 -0      xml-forrest/status.xml
  
  Index: status.xml
  ===================================================================
  RCS file: /home/cvs/xml-forrest/status.xml,v
  retrieving revision 1.10
  retrieving revision 1.11
  diff -u -r1.10 -r1.11
  --- status.xml	11 Aug 2002 14:19:38 -0000	1.10
  +++ status.xml	18 Aug 2002 07:44:56 -0000	1.11
  @@ -84,6 +84,10 @@
   
     <changes>
      <release version="0.1" date="2002">
  +    <action dev="DC" type="add" context="docs">
  +     Added new document <link href="your-project.html">Your Project
  +     - getting started with using Forrest</link>
  +    </action>
       <action dev="NKB" type="add" context="docs">
        Added to the &quot;forrest-site&quot; skin the ability to split source code
        larger than 80 chars in two or more lines.
  
  
  
  1.20      +1 -0      xml-forrest/src/documentation/content/xdocs/book.xml
  
  Index: book.xml
  ===================================================================
  RCS file: /home/cvs/xml-forrest/src/documentation/content/xdocs/book.xml,v
  retrieving revision 1.19
  retrieving revision 1.20
  diff -u -r1.19 -r1.20
  --- book.xml	31 Jul 2002 09:17:01 -0000	1.19
  +++ book.xml	18 Aug 2002 07:44:56 -0000	1.20
  @@ -36,6 +36,7 @@
       <!-- unfinished yet <menu-item label="URI Namespace" href="uri-namespace.html"/>
-->
       <menu-item label="Our Contract" href="forrest-contract.html"/>
       <menu-item label="The Forrestbot" href="forrestbot.html"/>
  +    <menu-item label="Using Forrest" href="your-project.html"/>
       <menu-item label="Libre" href="libre-intro.html"/>
       <menu-item label="DTD documentation" href="dtd-docs.html"/>
     </menu>
  
  
  
  1.13      +5 -1      xml-forrest/src/documentation/content/xdocs/faq.xml
  
  Index: faq.xml
  ===================================================================
  RCS file: /home/cvs/xml-forrest/src/documentation/content/xdocs/faq.xml,v
  retrieving revision 1.12
  retrieving revision 1.13
  diff -u -r1.12 -r1.13
  --- faq.xml	31 Jul 2002 02:09:34 -0000	1.12
  +++ faq.xml	18 Aug 2002 07:44:56 -0000	1.13
  @@ -45,7 +45,11 @@
      then copy the basic skin to make your own.
     </p>
     <p>
  -   However, Forrest is not quite ready. So please help us to reach that stage.</p>
  +   The <link href="forrestbot.html">forrestbot</link> is under-development
to
  +   automate the production of your documentation.
  +   Please set it up for your own projects by following this
  +   <link href="your-project.html">concise overview</link>. 
  +  </p>
    </answer>
   </faq>
   
  
  
  
  1.3       +4 -4      xml-forrest/src/documentation/content/xdocs/forrest-contract.xml
  
  Index: forrest-contract.xml
  ===================================================================
  RCS file: /home/cvs/xml-forrest/src/documentation/content/xdocs/forrest-contract.xml,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- forrest-contract.xml	8 Aug 2002 15:33:59 -0000	1.2
  +++ forrest-contract.xml	18 Aug 2002 07:44:56 -0000	1.3
  @@ -2,7 +2,7 @@
   <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
   <document> 
     <header> 
  -    <title>The Contract</title><authors><person name="Marc Portier"
email="mpo@outerthought.org"/></authors> 
  +    <title>Our Contract</title><authors><person name="Marc Portier"
email="mpo@outerthought.org"/></authors> 
       <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.
  @@ -31,9 +31,9 @@
           <code>{docroot}</code> equals to
           <code>{projecthome}/src/documentation</code></note> 
         <ul> 
  -        <li>provide XML content in <code>{docroot}/content/xdocs</code>
using
  -          the forrest DTDs,</li> 
  -        <li>provide content navigation metadata by sliding
  +        <li>provide XML content in <code>{docroot}/content/xdocs</code>
  +          according to the forrest DTDs,</li> 
  +        <li>provide content navigation metadata by adding
             <code>book.xml</code> and <code>tabs.xml</code> files
in there as well.
             (Forrest is working on a libre alternative to the book.xml approach).</li>

         <li>provide own xml project descriptor files in the directory <code>{projecthome}</code></li></ul>

  
  
  
  1.3       +22 -8     xml-forrest/src/documentation/content/xdocs/forrestbot.xml
  
  Index: forrestbot.xml
  ===================================================================
  RCS file: /home/cvs/xml-forrest/src/documentation/content/xdocs/forrestbot.xml,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- forrestbot.xml	8 Aug 2002 15:32:43 -0000	1.2
  +++ forrestbot.xml	18 Aug 2002 07:44:56 -0000	1.3
  @@ -6,13 +6,27 @@
       <authors><person name="Marc Portier" email="mpo@outerthought.org"/></authors>

       <abstract>This document explains how the Forrest project can be used to
         centrally build the HTML documentation for different projects. It also explains
  -      which pieces in the Forrest distribution come to play to achieve this
  +      which pieces in the Forrest distribution form this
         functionality, and how they could be extended in the future.</abstract> 
     </header> 
     <body> 
  -    <note>Related to this document it might be useful to check the
  -      <link href="forrest-contract.html">contract</link> that explains to which
rules
  -      your project should comply to when you want it to make use of Forrest.</note>

  +    <section> 
  +    <title>Foreword</title> 
  +    <p>This document explains how the Forrest project can be used to
  +      centrally build the HTML documentation for different projects.
  +      It also explains which pieces in the Forrest distribution form this
  +      functionality, and how they could be extended in the future.</p> 
  +    <p>See some related documents:</p>
  +    <ul>
  +     <li><link href="forrest-contract.html">Our Contract</link>
  +      - explains the rules with which your project should comply
  +     </li>
  +     <li><link href="your-project.html">Your Project</link>
  +      - getting started with using Forrest (concise overview of forrestbot)
  +     </li>
  +    </ul>
  +    </section> 
  +
       <section> 
         <title>Using the Forrest Bot</title> 
         <section> 
  @@ -25,7 +39,7 @@
           <source>build bot -Dbot.forrestbot.xconf=myOwn.conf.xml -Dtemplate.echo=[true|false]</source>

           <p>It is quite typical to perform this from a shell script that gets
             scheduled for execution on a regular basis.</p> 
  -        <p>The actions the bot is going to take are written down in the XML
  +        <p>The actions the bot is going to take are defined in the XML
             file pointed at with the <code>bot.forrestbot.xconf</code> System
property. (if
             not specified with <code>-Dbot.forrest.xconf</code> the default config
from the
             distribution is taken: <code>./forrestbot.conf.xml</code>) </p>

  @@ -34,7 +48,7 @@
           <title>Describing your project to the bot</title> 
           <fixme author="mpo">There is not yet a DTD for this configuration
             file.</fixme> 
  -        <p>The bot's work is written down in an XML configuration file, which
  +        <p>The bot's work is defined in an XML configuration file, which
             has one (optional) child-element for setting cross-project defaults followed
by
             a list of project-elements that hold the configuration for the various projects
             the bot is going to work on.</p> 
  @@ -85,7 +99,7 @@
           </ul> 
           <p>Inside the project element the configuration allows to set some
             parameters that get consumed in the template targets. This workstage dependant
  -          configuration always takes up the following layout: an element with the name
of
  +          configuration always takes the following layout: an element with the name of
             one of the tasks, and an optional type-attribute with nested elements that hold
             parameter names, with required name attribute holding the actual parameter
             value. Example:</p> 
  @@ -184,7 +198,7 @@
           </ul> 
           <p>What each of these templates is going to do with the parameters can
             be found in the templates.build.xml itself (at this stage) and is put out to
  -          the console if the bot is ran with the <code>-Dtemplate.echo=true</code>
  +          the console if the bot is run with the <code>-Dtemplate.echo=true</code>
             flag</p> 
           <section> 
             <title>Setting bot-wide defaults</title> 
  
  
  
  1.1                  xml-forrest/src/documentation/content/xdocs/your-project.xml
  
  Index: your-project.xml
  ===================================================================
  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
  
  <document>
   <header>
    <title>Your Project - getting started with using Forrest</title>
    <subtitle>Overview</subtitle>
    <version>0.1</version>
    <authors>
     <person name="David Crossley" email="crossley@apache.org"/>
    </authors>
   </header>
  
   <body>
   <section>
    <title>Goal</title>
    <p>
     You have your own project and you want to use Forrest to build the project
     documentation.
    </p>
   </section>
  
   <section>
    <title>Introduction</title>
    <p>
     The <strong>forrestbot</strong> will automatically build and publish your
     documentation on a regular basis. This document provides a concise overview.
     See
     <link href="forrestbot.html">The ForrestBot</link> for details and understand
     <link href="forrest-contract.html">Our Contract</link>.
    </p>
    <p>
     (Building the documentation for the actual Forrest project is a separate
     issue. Use
     <code>./build.sh clean docs</code> ... that will provide overview
     documentation about how Forrest operates and how you can help to improve it.)
    </p>
   </section>
  
   <section>
    <title>Establish project source directory</title>
    <p>The directory that contains our XML instances.</p>
    <ul>
     <li><code>PROJECT_HOME = /home/you/yourproject</code></li>
     <li><code>SRC_DOC = $PROJECT_HOME/src/documentation</code></li>
    </ul>
    <p>
     Our XML instance documents are at <code>$SRC_DOC/content/xdocs</code>
    </p>
   </section>
  
   <section>
    <title>Establish project configuration</title>
    <p>
  <code>cp $FORREST_HOME/forrestbot.conf.xml $PROJECT_HOME/yourproject.conf.xml</code>
     and edit it to replace the <code><![CDATA[<project>]]></code>
     definitions with our own, i.e.
    </p>
  <source><![CDATA[
    <project name="yourProject-local">
      <prepare>
          <skin name="basic"/>
      </prepare>
      <get-src type="local-copy">
        <content-dir name="/home/you/yourproject/src/documentation"/>
      </get-src>
      <deploy type="local-copy">
        <destination name="/var/www/html/yourproject"/>
      </deploy>
    </project>
  ]]></source>
   </section>
  
   <section>
    <title>Run forrestbot</title>
    <source>
  cd $FORREST_HOME
  ./build.sh bot \
  -Dbot.forrestbot.xconf=$PROJECT_HOME/yourproject.conf.xml \
  -Dtemplate.echo=true
    </source>
   </section>
  
   <section>
    <title>Next Steps</title>
    <p>Some enhancements to our local forrestbot would be ...</p>
    <ul>
     <li>Add our own skin at 
     <code>$SRC_DOC/skins/yourproject</code> by copying one of the skins from
     <code>$FORREST_HOME/src/resources/skins</code> (use basic or forrest-site)
     </li>
     <li>Configure another <code><![CDATA[<project>]]></code>
to conduct a secure
       copy to our public website.
     </li>
     <li>Get it to send us email about forrestbot activities.
     </li>
     <li>Send our feedback to <code>forrest-dev</code>
     </li>
    </ul>
   </section>
  
   <section>
    <title>Other methods</title>
    <p>The recent contribution of <strong>acorn</strong> (a simple Ant script
that
     bootstraps Forrest for a new project.
  See email discussion:
  <link href="http://marc.theaimsgroup.com/?l=forrest-dev&amp;m=102958410525990">http://marc.theaimsgroup.com/?l=forrest-dev&amp;m=102958410525990</link>
    </p>
   </section>
  
   </body>
  </document>
  
  
  

Mime
View raw message