Author: crossley
Date: Fri Dec 16 16:40:10 2005
New Revision: 357260
URL: http://svn.apache.org/viewcvs?rev=357260&view=rev
Log:
Publish some recent specific changes.
Modified:
forrest/site/contrib.html
forrest/site/contrib.pdf
forrest/site/docs_0_80/howto/howto-structurer-dsl.html
forrest/site/docs_0_80/howto/howto-structurer-dsl.pdf
forrest/site/tools/forrestbot.html
forrest/site/tools/forrestbot.pdf
Modified: forrest/site/contrib.html
URL:
http://svn.apache.org/viewcvs/forrest/site/contrib.html?rev=357260&r1=357259&r2=357260&view=diff
==============================================================================
--- forrest/site/contrib.html (original)
+++ forrest/site/contrib.html Fri Dec 16 16:40:10 2005
@@ -261,7 +261,7 @@
Forrest does not quite meet your needs then tell us about it.</li>
<li>Specifying/analysing/designing new features - and beyond. If you
- wish to get further involved with this, please join the <span
class="codefrag ">forrest-dev</span> mailing
+ wish to get further involved with this, please join the <span
class="codefrag">forrest-dev</span> mailing
list, install and try out Forrest and read some of the
<a href="mail-lists.html">mail archives</a>. You should have a
reasonable
fluency in XML technologies, some Java and Ant skills, and a basic
understanding of the Forrest
@@ -270,9 +270,9 @@
<li>Packaging easy-to-install packages (such as RPMs) for the myriad of
possible configurations out there. (The project does not maintain
anything but
- the basic <span class="codefrag ">.zip</span> and <span
class="codefrag ">.tar.gz</span> packages, but anyone is
+ the basic <span class="codefrag">.zip</span> and <span
class="codefrag">.tar.gz</span> packages, but anyone is
welcome to build their own specific packages and announce them on the
- <span class="codefrag ">forrest-dev</span> list)</li>
+ <span class="codefrag">forrest-dev</span> list)</li>
<li>... and there is just one other thing - don't forget to tell everyone
who asks, how great Forrest is! The more people that know about and
start
@@ -349,8 +349,8 @@
to automatically do this for certain file extensions.
To do it manually, make sure all line endings
are in your current OS's native format (the dos2unix and unix2dos
utilities
- may be useful) and then do a <span class="codefrag ">svn propset
svn:eol-style native myfilename.txt</span>
- and <span class="codefrag ">svn commit -m "fix line endings"
myfilename.txt</span>
+ may be useful) and then do a <span class="codefrag">svn propset
svn:eol-style native myfilename.txt</span>
+ and <span class="codefrag">svn commit -m "fix line endings"
myfilename.txt</span>
</p>
</div>
@@ -394,23 +394,37 @@
<a name="N100D2"></a><a name="patch"></a>
<h2 class="underlined_10">How to prepare and contribute patches</h2>
<div class="section">
-<p>If you use the current development version of Forrest, then do
- '<span class="codefrag ">svn update; svn status</span>' to see what
files that you
+<p>If you use the current development version of Forrest via Subversion,
+ then do
+ '<span class="codefrag">svn update; svn status</span>' to see what
files that you
have changed.
- Do '<span class="codefrag ">svn diff > mypatch.txt</span>' to make a
patch which
+ Do '<span class="codefrag">svn diff > mypatch.txt</span>' to make a
patch which
includes every change. To make a patch for a specific file, do
- <span class="codefrag ">svn diff
src/documentation/content/xdocs/faq.xml > faq.xml.diff</span>'.
+ <span class="codefrag">svn diff src/documentation/content/xdocs/faq.xml
> faq.xml.diff</span>'.
+ It is better to prepare the patch from the $FORREST_HOME directory
+ so that it contains a definite path to the document. However, be careful
+ that the patch does not contain other work-in-progress.
+ </p>
+<p>
For more information about working with SVN, see
<a href="http://svnbook.red-bean.com/";>Version Control with
Subversion</a> - the opensource SVN book.
- </p>
-<p>If you use a downloaded released version of Forrest, then do
- '<span class="codefrag ">diff -u faq.xml.orig faq.xml >
faq.xml.diff</span>'
+ </p>
+<p>
+ If you use a downloaded released version of Forrest (or don't use SVN),
+ then use the 'diff' command of your operating system:
+ '<span class="codefrag">diff -u faq.xml.orig faq.xml >
mypatch.txt</span>' (better
+ to do that from $FORREST_HOME directory). If you want to use the most
+ recent version of the documentation then grab its source file directly
+ from the
+ <a
href="http://svn.apache.org/repos/asf/forrest/trunk/site-author/content/xdocs/";>SVN
server</a>
+ (and tell us which Revision number you used).
</p>
<div class="note">
<div class="label">Note</div>
<div class="content">Please send all contributions via our
<a href="issues.html">issue tracker</a>.
+ and specify the Forrest version or svn version of the source.
</div>
</div>
<p>
@@ -421,7 +435,7 @@
</div>
-<a name="N100FD"></a><a name="revert"></a>
+<a name="N10104"></a><a name="revert"></a>
<h2 class="underlined_10">How to revert changes in SVN</h2>
<div class="section">
<p>Check out <a
href="http://svnbook.red-bean.com/en/1.0/ch04s04.html#svn-ch-4-sect-4.2";>http://svnbook.red-bean.com/en/1.0/ch04s04.html#svn-ch-4-sect-4.2</a>
@@ -429,7 +443,7 @@
</div>
-<a name="N1010B"></a><a name="tips"></a>
+<a name="N10112"></a><a name="tips"></a>
<h2 class="underlined_10">Contribution Notes and Tips</h2>
<div class="section">
<p> This is a collection of tips for contributing to the project in a
@@ -451,14 +465,14 @@
<li>Whenever you decide to start a new topic, then start with a fresh
new email message window. Do not use the "Reply to" button, because
- threaded mail-readers get confused (they utilise the <span
class="codefrag ">In-reply-to</span>
+ threaded mail-readers get confused (they utilise the <span
class="codefrag">In-reply-to</span>
header). If so, then your new topic will get lost in the previous
thread and go
unanswered. </li>
<li> Prepend your email subject line with a marker when that is
- appropriate, e.g. <span class="codefrag ">[Proposal]</span>,
- <span class="codefrag ">[RT]</span> (Random Thought which quickly
blossom into research topics
- :-), <span class="codefrag ">[STATUS]</span> (development status of
a certain facility). </li>
+ appropriate, e.g. <span class="codefrag">[Proposal]</span>,
+ <span class="codefrag">[RT]</span> (Random Thought which quickly
blossom into research topics
+ :-), <span class="codefrag">[STATUS]</span> (development status of a
certain facility). </li>
<li> When making changes to XML documentation, or any XML document for
that matter, use a validating XML editor. Here is some assistance
Modified: forrest/site/contrib.pdf
URL:
http://svn.apache.org/viewcvs/forrest/site/contrib.pdf?rev=357260&r1=357259&r2=357260&view=diff
==============================================================================
Binary files - no diff available.
Modified: forrest/site/docs_0_80/howto/howto-structurer-dsl.html
URL:
http://svn.apache.org/viewcvs/forrest/site/docs_0_80/howto/howto-structurer-dsl.html?rev=357260&r1=357259&r2=357260&view=diff
==============================================================================
--- forrest/site/docs_0_80/howto/howto-structurer-dsl.html (original)
+++ forrest/site/docs_0_80/howto/howto-structurer-dsl.html Fri Dec 16 16:40:10
2005
@@ -392,7 +392,7 @@
</div>
<div class="warning">
<div class="label">Warning</div>
-<div class="content"> The way we develope contracts will/may change with
introduction
+<div class="content"> The way we develop contracts will/may change with
introduction
of java based processing rather then xsl. Please keep this in mind and
help updating the documentation by sending patches. TIA. ;-) </div>
</div>
@@ -434,11 +434,11 @@
</div>
<p> We developed<strong> the structurer</strong> to let the user decide
where to place elements in e.g. html pages. We started this work with
the
- <span class="codefrag ">skinconf.xml</span> where you could configure
certain elements and
+ <span class="codefrag">skinconf.xml</span> where you could configure
certain elements and
their positions. These elements were known under certain names. It was
up
to the skin designer to support this configuration and the elements. </p>
<p> The work started with grouping elements (the ones from skinconf). We
- used css-contracts that we added as @attributes e.g. <span
class="codefrag "><div id="content-main"/>
+ used css-contracts that we added as @attributes e.g. <span
class="codefrag"><div id="content-main"/>
</span>. That made it possible to use the same elements in different
skins. For the full list refer to the <a
href="http://svn.apache.org/repos/asf/forrest/trunk/main/webapp/skins/leather-dev/contracts.initial.txt";>
initial contract list </a>
@@ -452,8 +452,8 @@
<strong>forrest:hook</strong>s are containers that are only used for
layout reasons. They <strong>do not</strong> add any content nor
functionality to the output. They add <strong>only</strong> layout
- information to the output. Actually e.g. a <span class="codefrag
"><forrest:hook name="layoutId"/>
- </span> will be transformed to <span class="codefrag "><div
id="layoutId"/>
+ information to the output. Actually e.g. a <span
class="codefrag"><forrest:hook name="layoutId"/>
+ </span> will be transformed to <span class="codefrag"><div
id="layoutId"/>
</span>
</p>
<p>
@@ -508,16 +508,22 @@
</div>
<p> In this section we will create a new structurer. We will override the
default structurer of the themer-plugin for the index page of the <a
href="../../docs_0_80/howto/howto-structurer-install.html">v2</a>. For that we
will create a
- file called <span class="codefrag ">index.fv</span> and save it in our
xdocs directory.
+ file called <span class="codefrag">index.fv</span> and save it in our
xdocs directory.
This will make <strong>only</strong> the index.html page look
different
from the rest of the project. </p>
+<div class="note">
+<div class="label">Note</div>
+<div class="content">You can set a view for an individual file, a directory,
or the whole site. To address multiple files in a directory call your <span
class="codefrag">.fv</span> file <span class="codefrag">common.fv</span>. If
Forrest doesn't find a <span class="codefrag">.fv</span> file with the same
name as the current file it will use the common.fv file in that directory, or
the first one it finds going upwards through the directory structure.
+ <span class="codefrag">common.fv</span> files affect all subdirectories
unless they are overidden by another <span class="codefrag">common.fv</span> or
a file-specific <span class="codefrag">foo.fv</span> file.
+ </div>
+</div>
<p> Remember: pointing your browser to
- <span class="codefrag ">http://localhost:8888/ls.contracts.html</span>
will show a page
+ <span class="codefrag">http://localhost:8888/ls.contracts.html</span>
will show a page
with all contracts and themes that you can use in your project
provided
by forrest. </p>
<p> Let us use the blank structurer from the earlier step and add the
content-main contract. In ls.contracts.html we find the information
for
- how to use the contract in our structurer. Our <span class="codefrag
">index.fv</span>
+ how to use the contract in our structurer. Our <span
class="codefrag">index.fv</span>
should look like: </p>
<pre class="code"><forrest:views
xmlns:forrest="http://apache.org/forrest/templates/1.0";
@@ -540,16 +546,16 @@
<p>A contract has to request the data model it want to transform. This
happends by defining forrest:properties which have the same name like
the contract. In our case we want the HTML rendered from intermediate
- format (**.body.xml). This we are going to include via: <span
class="codefrag "><jx:import
uri="cocoon://#{$cocoon/parameters/getRequest}.body.xml"/>
+ format (**.body.xml). This we are going to include via: <span
class="codefrag"><jx:import
uri="cocoon://#{$cocoon/parameters/getRequest}.body.xml"/>
</span>
</p>
<p>Contracts can offer some property configuration of the outcome of
- the transformation. In our case <span class="codefrag
"><forrest:property name="content-main-conf">
+ the transformation. In our case <span
class="codefrag"><forrest:property name="content-main-conf">
<headings type="underlined"/>
</forrest:property>. </span>
</p>
<p> Lets try our new structurer by pointing to
- <span class="codefrag ">http://localhost:8888/index.html</span>. We
will see only the
+ <span class="codefrag">http://localhost:8888/index.html</span>. We
will see only the
main content. Now let us add the section navigation to our structurer.
The contract usage in the structurer can be looked up in
ls.contracts.html. Our structurer now looks like: </p>
@@ -582,9 +588,9 @@
<p> We now find the main content and the section navigation after each
other and in the order we placed them in the structurer, but we want
it
next to each other (left: nav-section; right: content-main). </p>
-<a name="N100E6"></a><a name="hookstructurer"></a>
+<a name="N100FB"></a><a name="hookstructurer"></a>
<h3 class="underlined_5">Hooks in the structurer</h3>
-<p> We will use now the first time a <span class="codefrag "><forrest:hook
name="layoutId"/>
+<p> We will use now the first time a <span class="codefrag"><forrest:hook
name="layoutId"/>
</span>. Hooks are the styling side of the structurer. We can imitate
arbitrary html skeleton with their help. Before we explain how to use
your own css in the structurer, we will use the default css. You can
@@ -599,7 +605,7 @@
border: thin dashed #565248;
}
</pre>
-<p> With this information we know to use <span class="codefrag
"><forrest:hook name="leftbar"/>
+<p> With this information we know to use <span
class="codefrag"><forrest:hook name="leftbar"/>
</span> and add contracts into that container. </p>
<p> If we want to put the nav-section contract into the left-hand side
position of the site we need to place the contract into that hook.
@@ -637,12 +643,12 @@
</forrest:view>
</forrest:views>
</pre>
-<a name="N1010B"></a><a name="cssstructurer"></a>
+<a name="N10120"></a><a name="cssstructurer"></a>
<h3 class="underlined_5">CSS in the structurer</h3>
<p>We now know how to place contracts and hooks in our structurer. Until
this stage we only used the common.css. CSS-support of the structurer
is as easy as placing contracts/hooks. To override the common.css
- stylesheet we use another tag within our structurer <span
class="codefrag "><forrest:css />
+ stylesheet we use another tag within our structurer <span
class="codefrag"><forrest:css />
</span>. </p>
<p>You can add inline and linked css with the structurer. As soon as you
use forrest:css you will disable the fallback css support from
@@ -665,8 +671,8 @@
<div class="label">Note</div>
<div class="content">
-<span class="codefrag "><forrest:css /></span> needs to be the direct
child of
- <span class="codefrag "><forrest:view type="html"></span>
+<span class="codefrag"><forrest:css /></span> needs to be the direct
child of
+ <span class="codefrag"><forrest:view type="html"></span>
</div>
</div>
@@ -709,7 +715,7 @@
</forrest:views>
</pre>
<p>As a second example, let us change
- as well the content-main by adding another hook <span class="codefrag
"><forrest:hook name="content"/>
+ as well the content-main by adding another hook <span
class="codefrag"><forrest:hook name="content"/>
</span> We need to add the new layout container to our inline css: </p>
<pre class="code">
/* The actual content */
@@ -774,7 +780,7 @@
</div>
</div>
</div>
-<a name="N1014D"></a><a name="Further Reading"></a>
+<a name="N10162"></a><a name="Further Reading"></a>
<h2 class="underlined_10">Further Reading</h2>
<div class="section">
<p> Congratulations you are now able to work with the structurer. From here
@@ -790,7 +796,7 @@
</ul>
</div>
-<a name="N1015F"></a><a name="Feedback"></a>
+<a name="N10174"></a><a name="Feedback"></a>
<h2 class="underlined_10">Feedback</h2>
<div class="section">
<p> Please provide feedback about this document via the <a
href="../../mail-lists.html">mailing lists</a>. </p>
Modified: forrest/site/docs_0_80/howto/howto-structurer-dsl.pdf
URL:
http://svn.apache.org/viewcvs/forrest/site/docs_0_80/howto/howto-structurer-dsl.pdf?rev=357260&r1=357259&r2=357260&view=diff
==============================================================================
Binary files - no diff available.
Modified: forrest/site/tools/forrestbot.html
URL:
http://svn.apache.org/viewcvs/forrest/site/tools/forrestbot.html?rev=357260&r1=357259&r2=357260&view=diff
==============================================================================
--- forrest/site/tools/forrestbot.html (original)
+++ forrest/site/tools/forrestbot.html Fri Dec 16 16:40:10 2005
@@ -165,16 +165,21 @@
<a href="#Using+Forrestbot">Using Forrestbot</a>
</li>
<li>
-<a href="#Creating+a+buildfile">Creating a buildfile</a>
+<a href="#Creating+a+Forrestbot+Project+Buildfile">Creating a Forrestbot
Project Buildfile</a>
<ul class="minitoc">
<li>
<a href="#Workstages">Workstages</a>
+<ul class="minitoc">
+<li>
+<a href="#Correct+Use+of+getsrc.local">Correct Use of getsrc.local</a>
+</li>
+</ul>
</li>
<li>
<a href="#Workstage+Properties">Workstage Properties</a>
<ul class="minitoc">
<li>
-<a href="#Misc+Properties">Misc Properties</a>
+<a href="#Misc.+Properties">Misc. Properties</a>
</li>
<li>
<a href="#getsrc.clean-workdir">getsrc.clean-workdir</a>
@@ -220,7 +225,7 @@
</ul>
</li>
<li>
-<a href="#Forrestbot+design">Forrestbot design</a>
+<a href="#Forrestbot+Design">Forrestbot Design</a>
</li>
</ul>
</div>
@@ -228,50 +233,52 @@
<a name="N1000D"></a><a name="Overview"></a>
<h2 class="underlined_10">Overview</h2>
<div class="section">
-<p>Forrestbot lets you automate building and deploying websites. The
- whole process gets the source docs, builds it, then deploys the site
- where you want it to go. It can also notify you afterwards, and it
- keeps a log of the build process. To accomplish these tasks Forrestbot
- uses four "workstages" (getsrc, build, deploy, notify). Each workstage
- has various "implementations" (e.g. getsrc has getsrc.cvs or getsrc.svn
- or getsrc.local implementations) which
- have various properties that may be set, depending upon the
- implementations chosen.</p>
+<p>Forrestbot lets you automate building and deploying websites. The
+ whole process gets the source docs, builds the site, then deploys it
+ where you want it to go. Forrestbot can also notify you afterwards, and
+ it keeps a log of the build process. To accomplish these tasks,
+ Forrestbot uses four "workstages" (getsrc, build, deploy, notify). Each
+ workstage has various implementations (e.g., getsrc has getsrc.cvs or
+ getsrc.svn or getsrc.local implementations), which have various
+ properties that may be set, depending upon the implementations
+ chosen.</p>
</div>
<a name="N10017"></a><a name="Using+Forrestbot"></a>
<h2 class="underlined_10">Using Forrestbot</h2>
<div class="section">
-<p>You need to create a customized buildfile directing Forrestbot's work
- and then simply execute:</p>
+<p>You need to create a customized buildfile directing Forrestbot's work
+ and then simply execute:</p>
<pre class="code">forrest -f mybuildfile.xml</pre>
-<p>The next section explains how to create your buildfile.</p>
+<p>This project buildfile is simply an Ant buildfile with specific
+ targets that control Forrestbot's operation. The next section explains
+ how to create such a buildfile. For details on the syntax of Ant
+ buildfiles and the operation of Ant itself consult the <a
href="http://ant.apache.org/";>Ant documentation</a>.</p>
</div>
-<a name="N10028"></a><a name="Creating+a+buildfile"></a>
-<h2 class="underlined_10">Creating a buildfile</h2>
+<a name="N1002C"></a><a name="Creating+a+Forrestbot+Project+Buildfile"></a>
+<h2 class="underlined_10">Creating a Forrestbot Project Buildfile</h2>
<div class="section">
-<p>Within the new buildfile you need to first set properties needed by
- the workstages you are going to use and then specify what
- implementations will be used by each workstage.</p>
-<div class="fixme">
-<div class="label">Fixme (open)</div>
-<div class="content">This seems backwards since the properties are dependent
-on the implementations - no?</div>
-</div>
-<p>This sample buildfile can be used as a base from which to customize
- your own buildfile. The file starts with the project name and default
- workstage target, then sets the specific properties we will need to
get
- the source, set up notification and indicate the deploy location. It
then
- specifies which implementations we will use and finishes up with
- importing the forrestbot.xml file.</p>
-<div class="fixme">
-<div class="label">Fixme (open)</div>
-<div class="content">Is "default workstage target" the correct term for
-default="main"?</div>
-</div>
+<p>Within the new buildfile, you need to first set properties needed by
+ the workstages you are going to use and then specify which
+ implementations will be used by each workstage. Note that the properties
+ need to be set at the global scope (as children of
+ <span class="codefrag"><project></span>, i.e., outside of
+ <span class="codefrag"><target></span> elements) in order for your
settings to
+ override the defaults in the Forrestbot implementation. Other than that,
+ the property definitions can appear anywhere before the
+ <span class="codefrag"><import></span> task.</p>
+<p>This sample buildfile can be used as a base from which to customize
+ your own buildfile. The file starts with the project name and default
+ target, then sets the specific properties we need to get the source,
+ indicate the deployment location, and set up notification. It then
+ specifies which implementations we will use and finishes up with
+ importing the <span class="codefrag">forrestbot.xml</span> file. The
'main' target, which
+ is specified as the default here, is a convenience target (defined in
+ <span class="codefrag">forrestbot.xml</span>) that executes the four
workstages (getsrc,
+ build, deploy, notify) sequentially.</p>
<pre class="code"><project name="mysampleproject" default="main">
<property name="notify.email.host" value="smtp.myhost.com"/>
<property name="notify.email.to" value="[EMAIL PROTECTED]"/>
@@ -302,148 +309,171 @@
</project>
</pre>
-<a name="N10040"></a><a name="Workstages"></a>
+<a name="N1004B"></a><a name="Workstages"></a>
<h3 class="underlined_5">Workstages</h3>
-<p>It is only necessary to include the specific target implementations in
- the buildfile if we want to override the default implementations. The
- following tables show the various workstages and which implementations
- may be used for each and which is the default.</p>
+<p>It is only necessary to include specific target implementations in
+ the buildfile if we want to override the default implementations. The
+ following table shows the various workstages, which implementations
+ may be used for each, and which one is the default.</p>
<table class="ForrestTable" cellspacing="1" cellpadding="4">
-
-<tr>
+<tr>
+
<th colspan="1" rowspan="1">Workstage</th>
- <th colspan="1" rowspan="1">Implementations</th>
-
+ <th colspan="1" rowspan="1">Implementations</th>
+
</tr>
-
-<tr>
+<tr>
+
<td colspan="1" rowspan="1">getsrc</td>
- <td colspan="1" rowspan="1">
+ <td colspan="1" rowspan="1">
<ul>
-
+
<li>
<a href="#getsrc.local">getsrc.local</a>
</li>
-
+
<li>
<a href="#getsrc.cvs">getsrc.cvs</a> (default)</li>
-
+
<li>
<a href="#getsrc.svn">getsrc.svn</a>
</li>
-
+
</ul>
</td>
-
+
</tr>
-
-<tr>
+<tr>
+
<td colspan="1" rowspan="1">build</td>
- <td colspan="1" rowspan="1">
+ <td colspan="1" rowspan="1">
<ul>
-
+
<li>
<a href="#build.forrest">build.forrest</a>
</li>
-
+
</ul>
</td>
-
+
</tr>
-
-<tr>
+<tr>
+
<td colspan="1" rowspan="1">deploy</td>
- <td colspan="1" rowspan="1">
+ <td colspan="1" rowspan="1">
<ul>
-
+
<li>
-<a href="#deploy.local">deploy.local</a> (default)</li>
+<a href="#deploy.local">deploy.local</a>
+ (default)</li>
-
+
<li>
<a href="#deploy.scp">deploy.scp</a>
</li>
-
+
<li>
<a href="#deploy.cvs">deploy.cvs</a>
</li>
-
+
<li>
<a href="#deploy.svn">deploy.svn</a>
</li>
-
+
+
<li>
<a href="#deploy.ftp">deploy.ftp</a>
</li>
-
+
</ul>
</td>
-
+
</tr>
-
-<tr>
+<tr>
+
<td colspan="1" rowspan="1"><a href="#notify">notify</a></td>
- <td colspan="1" rowspan="1">
+ <td colspan="1" rowspan="1">
<ul>
-
+
<li>
-<a href="#notify.local">notify.local</a> (default)</li>
+<a href="#notify.local">notify.local</a>
+ (default)</li>
-
+
<li>
<a href="#notify.email">notify.email</a>
</li>
-
+
</ul>
</td>
-
+
</tr>
-
+
</table>
-<p>If you want to do more advanced processing for your project, you can
- override the 'main' target, which by default is <span class="codefrag
"><target
- name="main" depends="getsrc, build, deploy, notify"/></span>, create
- your own implementation of a workstage, or use any other ant tasks to do
- additional work.</p>
-<div class="fixme">
-<div class="label">Fixme (open)</div>
-<div class="content">How do you create your own implementation? Can you
-create a different default target than main - how do you override the
-default?</div>
-</div>
-<p></p>
-<a name="N100DA"></a><a name="Workstage+Properties"></a>
+<p>If you want to do more advanced processing for your project, you
+ can override the 'main' target, which by default is <span
class="codefrag"><target
+ name="main" depends="getsrc, build, deploy, notify"/></span>,
+ create your own implementation of a workstage, or use any other ant
+ tasks to do additional work. In order to create your own workstage
+ implementation, define the workstage target in question in your
+ <span class="codefrag">mybuildfile.xml</span> anywhere before the
+ <span class="codefrag"><import></span> task. This will override
the default
+ implementation provided by Forrestbot.</p>
+<p>Also, you can choose a different target as the default by changing
+ the <span class="codefrag">default</span> attribute of <span
class="codefrag"><project></span>.
+ For example, you will much more frequently do a 'build' without a
+ 'deploy' during the development of your website, and only at the end
+ do an actual 'deploy', so you might want to choose 'build' as your
+ default target.</p>
+<a name="N100ED"></a><a name="Correct+Use+of+getsrc.local"></a>
+<h4>Correct Use of getsrc.local</h4>
+<p>There is a wrinkle when using the 'getsrc.local' implementation
+ of the 'getsrc' workstage. If you define your own 'getsrc.local'
+ target, make sure it starts with the <span
class="codefrag"><property></span>
+ task given here:</p>
+<pre class="code"><target name="getsrc.local">
+ <property name="build.home-dir" location="${getsrc.local.root-dir}"/>
+ [...]
+</target></pre>
+<p>Alternatively (and preferably), define your 'getsrc' target like
+ this:</p>
+<pre class="code"><target name="getsrc" depends="getsrc.clean-workdir,
getsrc.get, getsrc.local"/></pre>
+<p>and then implement the actual fetching of the sources in the
+ 'getsrc.get' target. This latter approach is safer since it is more
+ likely to be forward-compatible with future versions of
+ Forrestbot.</p>
+<a name="N10109"></a><a name="Workstage+Properties"></a>
<h3 class="underlined_5">Workstage Properties</h3>
<p>Each workstage implementation is configurable with properties. The
following tables describe each property and whether or not you are
required to set it in your buildfile.</p>
-<p>Many workstage properties use usernames and passwords. You may want to
- keep them out of your project's xml buildfile (especially if you store
- that file in CVS
- or SVN). A nice way to do this is make a simple buildfile (e.g.
- my-settings.xml) that just sets those properties (don't include it in
- CVS/SVN). Then in your project buildfile, have <span class="codefrag
"><import
- file="my-settings.xml"/></span>.</p>
-<a name="N100E9"></a><a name="Misc+Properties"></a>
-<h4>Misc Properties</h4>
+<p>Many workstage properties use usernames and passwords. You may want
+ to keep them out of your project's Ant buildfile (especially if you
+ store that file in CVS or SVN). A nice way to do this is to create a
+ separate properties file (e.g., <span
class="codefrag">auth.properties</span>) that
+ just sets those properties (don't include it in CVS/SVN). Then, at the
+ top of your project buildfile, have <span class="codefrag"><property
+ file="auth.properties"/></span>.</p>
+<a name="N1011B"></a><a name="Misc.+Properties"></a>
+<h4>Misc. Properties</h4>
<table class="ForrestTable" cellspacing="1" cellpadding="4">
<tr>
@@ -473,13 +503,12 @@
</tr>
</table>
-<a name="N10120"></a><a name="getsrc.clean-workdir"></a>
+<a name="N10152"></a><a name="getsrc.clean-workdir"></a>
<h4>getsrc.clean-workdir</h4>
-<p>This should be executed before a getsrc implementation is executed.
- For example, <span class="codefrag "><target name="getsrc"
- depends="getsrc.clean-workdir, getsrc.svn"/></span>
-</p>
-<a name="N1012C"></a><a name="getsrc.local"></a>
+<p>This should be executed before a getsrc implementation is
+ executed, e.g., <span class="codefrag"><target name="getsrc"
+ depends="getsrc.clean-workdir, getsrc.svn"/></span>.</p>
+<a name="N1015F"></a><a name="getsrc.local"></a>
<h4>getsrc.local</h4>
<table class="ForrestTable" cellspacing="1" cellpadding="4">
@@ -501,7 +530,7 @@
<td colspan="1" rowspan="1">getsrc.local.root-dir</td>
<td colspan="1" rowspan="1">Absolute path to the project's root
directory on the local
- computer. Use <strong>location=</strong> instead of
+ computer. Use <strong>location=</strong> instead of
<strong>value=</strong> for this <property></td>
<td colspan="1" rowspan="1"></td>
@@ -511,7 +540,7 @@
</tr>
</table>
-<a name="N10169"></a><a name="getsrc.cvs"></a>
+<a name="N1019C"></a><a name="getsrc.cvs"></a>
<h4>getsrc.cvs</h4>
<table class="ForrestTable" cellspacing="1" cellpadding="4">
@@ -584,8 +613,8 @@
<td colspan="1" rowspan="1">getsrc.cvs.module</td>
- <td colspan="1" rowspan="1">CVS module name (an alias, or full
path) to the directory that
- contains forrest.properties</td>
+ <td colspan="1" rowspan="1">CVS module name (an alias for or the
full path to the
+ directory that contains forrest.properties)</td>
<td colspan="1" rowspan="1">${ant.project.name}</td>
@@ -607,7 +636,7 @@
</tr>
</table>
-<a name="N10211"></a><a name="getsrc.svn"></a>
+<a name="N10244"></a><a name="getsrc.svn"></a>
<h4>getsrc.svn</h4>
<table class="ForrestTable" cellspacing="1" cellpadding="4">
@@ -651,7 +680,7 @@
</tr>
</table>
-<a name="N1025F"></a><a name="build.forrest"></a>
+<a name="N10292"></a><a name="build.forrest"></a>
<h4>build.forrest</h4>
<table class="ForrestTable" cellspacing="1" cellpadding="4">
@@ -694,7 +723,7 @@
</tr>
</table>
-<a name="N102AE"></a><a name="deploy.local"></a>
+<a name="N102E1"></a><a name="deploy.local"></a>
<h4>deploy.local</h4>
<table class="ForrestTable" cellspacing="1" cellpadding="4">
@@ -715,9 +744,10 @@
<td colspan="1" rowspan="1">deploy.local.dir</td>
- <td colspan="1" rowspan="1">Path to deploy site to - the dir
that would be the equivalant
- of build/site dir. Relative paths will be relative to
- project forrestbot descriptor file.</td>
+ <td colspan="1" rowspan="1">Path to deploy site to - the dir
that would be the
+ equivalant of build/site dir. Relative paths are relative to
+ ${basedir}, which defaults to the dir containing the Forrestbot
+ project buildfile (mybuildfile.xml).</td>
<td colspan="1" rowspan="1">sites/${ant.project.name}</td>
@@ -726,11 +756,12 @@
</tr>
</table>
-<a name="N102E6"></a><a name="deploy.scp"></a>
+<a name="N10319"></a><a name="deploy.scp"></a>
<h4>deploy.scp</h4>
-<p>${user.home}/.ssh/known_hosts must properly recognize the host, so
- you should manually make an ssh connection to the host if you never
- have before.</p>
+<p>
+<span class="codefrag">${user.home}/.ssh/known_hosts</span> must properly
+ recognize the host, so you should manually make an ssh connection to
+ the host if you never have before.</p>
<table class="ForrestTable" cellspacing="1" cellpadding="4">
<tr>
@@ -773,7 +804,7 @@
</tr>
</table>
-<a name="N10336"></a><a name="deploy.cvs"></a>
+<a name="N1036B"></a><a name="deploy.cvs"></a>
<h4>deploy.cvs</h4>
<p>This is only available on *nix operating systems.</p>
<table class="ForrestTable" cellspacing="1" cellpadding="4">
@@ -870,7 +901,7 @@
</tr>
</table>
-<a name="N103E2"></a><a name="deploy.svn"></a>
+<a name="N10417"></a><a name="deploy.svn"></a>
<h4>deploy.svn</h4>
<table class="ForrestTable" cellspacing="1" cellpadding="4">
@@ -940,7 +971,7 @@
</tr>
</table>
-<a name="N1045C"></a><a name="deploy.ftp"></a>
+<a name="N10491"></a><a name="deploy.ftp"></a>
<h4>deploy.ftp</h4>
<table class="ForrestTable" cellspacing="1" cellpadding="4">
@@ -1001,7 +1032,7 @@
<td colspan="1" rowspan="1">deploy.ftp.remotedir</td>
<td colspan="1" rowspan="1">The directory to upload to (this can
be an absolute path or
- relative to the FTP user's default directory)</td>
+ relative to the FTP user's default directory)</td>
<td colspan="1" rowspan="1">incoming</td>
@@ -1010,7 +1041,7 @@
</tr>
</table>
-<a name="N104D9"></a><a name="notify"></a>
+<a name="N1050E"></a><a name="notify"></a>
<h4>notify</h4>
<p>These settings are used by all notify implementations.</p>
<table class="ForrestTable" cellspacing="1" cellpadding="4">
@@ -1108,10 +1139,10 @@
</tr>
</table>
-<a name="N10583"></a><a name="notify.local"></a>
+<a name="N105B8"></a><a name="notify.local"></a>
<h4>notify.local</h4>
<p>No properties.</p>
-<a name="N1058D"></a><a name="notify.email"></a>
+<a name="N105C2"></a><a name="notify.email"></a>
<h4>notify.email</h4>
<table class="ForrestTable" cellspacing="1" cellpadding="4">
@@ -1170,22 +1201,28 @@
</div>
-<a name="N105F5"></a><a name="Forrestbot+design"></a>
-<h2 class="underlined_10">Forrestbot design</h2>
+<a name="N1062A"></a><a name="Forrestbot+Design"></a>
+<h2 class="underlined_10">Forrestbot Design</h2>
<div class="section">
-<p>Forrest and forrestbot use ant buildfiles extensively. Ant 1.6's import
- task is used to import multiple buildfiles into a single build. The
- following is the flow of control when running forrestbot:</p>
+<p>Forrest and Forrestbot use Ant buildfiles extensively. Ant 1.6's
+ <span class="codefrag"><import></span> task is used to import
multiple buildfiles
+ into a single build. The following is the flow of control when running
+ Forrestbot:</p>
<ul>
-<li>Your buildfile<ul>
+<li>Your project buildfile (<span class="codefrag">mybuildfile.xml</span>)<ul>
-<li>forrestbot.xml<ul>
+<li>
+<span
class="codefrag">$FORREST_HOME/tools/forrestbot/core/forrestbot.xml</span>
+<ul>
-<li>workstage buildfiles</li>
+<li>Workstage buildfiles
+ (<span
class="codefrag">$FORREST_HOME/tools/forrestbot/core/{getsrc,build,deploy,notify}.xml</span>)</li>
-<li>forrest.build.xml</li>
+<li>
+<span class="codefrag">$FORREST_HOME/main/forrest.build.xml</span>
+</li>
</ul>
</li>
@@ -1194,18 +1231,16 @@
</li>
</ul>
-<p>The workstage buildfiles set up the properties and files so that the
- main forrest buildfile (forrest.build.xml) will run. After it is run,
- other workstage buildfiles can implement reporting, deployment, or other
- post-build activities.</p>
-<p>Your buildfile can specify which workstages you want to use, set
- properties for them, and do any additional pre- and post-processing.</p>
-<div class="fixme">
-<div class="label">Fixme (open)</div>
-<div class="content">Which of these (Your buildfile/workstage buildfile) is
-the "project buildfile" referred to elsewhere on this page, if any? If it is
-"Your buildfile" can I also create workstage buildfiles? If so, how?</div>
-</div>
+<p>The workstage buildfiles define the default workstage implementations
+ and set up the properties and files so that targets in the main Forrest
+ buildfile (<span class="codefrag">forrest.build.xml</span>) will run.
After those targets
+ are executed, the targets in the workstage buildfiles can perform
+ reporting, deployment, or other post-build activities.</p>
+<p>Your project buildfile specifies the workstages you want to use, sets
+ properties for them, and does any additional pre- and post-processing.
+ In addition, you can override the default workstage implementations by
+ defining the relevant targets in your project buildfile before the
+ <span class="codefrag"><import></span> task (see the example
above).</p>
</div>
</div>
Modified: forrest/site/tools/forrestbot.pdf
URL:
http://svn.apache.org/viewcvs/forrest/site/tools/forrestbot.pdf?rev=357260&r1=357259&r2=357260&view=diff
==============================================================================
Binary files - no diff available.
