<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://apache.org/forrest/dtd/document-v12.dtd">

<document>
 <header>
  <title>Forrestbot introduction</title>
  <subtitle>Getting started with using Forrestbot</subtitle>
  <version>0.2</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. The versatile ForrestBot can retrieve
   source XML instances from various type of repository (e.g. local filesystem,
   local CVS, remote CVS), generate the documents, and copy the result to a
   local or remote location (optionally via secure methods). It can be run
   from the command-line as part of your documentation edit-build-review cycle,
   it can be called from cron to automate your website update, it can operate
   as a centralised docs-build service for a set of remote projects, it can do
   tasks in parallel, and do even more.
   See some websites that are automatically built with ForrestBot at
   <link href="http://forrestbot.cocoondev.org/">http://forrestbot.cocoondev.org/</link>
  </p>
  <p>
   This document provides a concise overview of one particular scenario. See
   <link href="site:forrestbot">The ForrestBot</link> for details and understand
   <link href="site:forrest-contract">Our Contract</link>.
   We assume that you have built and configured Forrest as described in 
   <link href="your-project.html">Using Forrest</link>.
  </p>
  <p>
   Please send your feedback to <code>forrest-dev</code> - the ForrestBot
   will be enhanced to meet diverse needs.
  </p>
  <p>
   (Building the documentation for the actual Forrest project is a separate
   issue. Use
   <code>./build.sh site</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 your 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>
   Your XML instance documents are at <code>$SRC_DOC/content/xdocs</code>
  </p>
 </section>

 <section>
  <title>Establish project configuration</title>
  <p>See the sample configurations at
   <code>xml-forrest/src/resources/forrestbot/samples/</code>
   copy one 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="forrest-site"/>
    </prepare>
    <get-src type="local-copy">
      <project-dir name="/home/you/yourproject" />
      <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><![CDATA[
[you@locahost]$ cd $PROJECT_HOME
[you@locahost]$ forrestbot -Dbot.config=<name>
... where <name> is the pathname to your configuration file.
]]></source>
  <p>There are also convenience scripts for automation.
   See 
   <code>xml-forrest/src/resources/forrestbot/scripts/README.txt</code>
  </p>
 </section>

 <section>
  <title>Next Steps</title>
  <p>Some enhancements to your ForrestBot would be ...</p>
  <ul>
   <li>Add your own skin as described in 
   <link href="your-project.html">Using Forrest</link>.
   </li>
   <li>Configure another <code><![CDATA[<project>]]></code> to conduct a secure
     copy to your public website.
   </li>
   <li>Instruct ForrestBot to send you email about the activities.
   </li>
   <li>Manage your XML instances with CVS and instruct ForrestBot to get
     the source.
   </li>
   <li>Use the "Forrestbot web interface" (website staging application).
   <code>xml-forrest/src/resources/forrestbot/webapp/WEB-INF/README.txt</code>
   </li>
  </ul>
 </section>

 <section>
  <title>Other methods</title>
  <p>See the <link href="site:your-project">Using Forrest</link> document.</p>
  <p>Forrest can also run as a dynamic webapp.</p>
 </section>

 </body>
</document>
