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 "forrest-site" 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&m=102958410525990">http://marc.theaimsgroup.com/?l=forrest-dev&m=102958410525990</link>
</p>
</section>
</body>
</document>
|