forrest-svn mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cross...@apache.org
Subject svn commit: r357260 - in /forrest/site: contrib.html contrib.pdf docs_0_80/howto/howto-structurer-dsl.html docs_0_80/howto/howto-structurer-dsl.pdf tools/forrestbot.html tools/forrestbot.pdf
Date Sat, 17 Dec 2005 00:40:31 GMT
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 &gt; mypatch.txt</span>' to make
a patch which
+       Do '<span class="codefrag">svn diff &gt; 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 &gt;
faq.xml.diff</span>'.
+       <span class="codefrag">svn diff src/documentation/content/xdocs/faq.xml &gt;
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 &gt; 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 &gt; 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 ">&lt;div
id="content-main"/&gt;
+      used css-contracts that we added as @attributes e.g. <span class="codefrag">&lt;div
id="content-main"/&gt;
        </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 ">&lt;forrest:hook
name="layoutId"/&gt;
-      </span> will be transformed to <span class="codefrag ">&lt;div id="layoutId"/&gt;

+      information to the output. Actually e.g. a <span class="codefrag">&lt;forrest:hook
name="layoutId"/&gt;
+      </span> will be transformed to <span class="codefrag">&lt;div id="layoutId"/&gt;

       </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">&lt;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
">&lt;jx:import uri="cocoon://#{$cocoon/parameters/getRequest}.body.xml"/&gt;
+        format (**.body.xml). This we are going to include via: <span class="codefrag">&lt;jx:import
uri="cocoon://#{$cocoon/parameters/getRequest}.body.xml"/&gt;
          </span>
 </p>
 <p>Contracts can offer some property configuration of the outcome of 
-            the transformation. In our case <span class="codefrag ">&lt;forrest:property
name="content-main-conf"&gt;
+            the transformation. In our case <span class="codefrag">&lt;forrest:property
name="content-main-conf"&gt;
         &lt;headings type="underlined"/&gt;
       &lt;/forrest:property&gt;. </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 ">&lt;forrest:hook
name="layoutId"/&gt;
+<p> We will use now the first time a <span class="codefrag">&lt;forrest:hook
name="layoutId"/&gt;
          </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 ">&lt;forrest:hook
name="leftbar"/&gt;
+<p> With this information we know to use <span class="codefrag">&lt;forrest:hook
name="leftbar"/&gt;
         </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 @@
   &lt;/forrest:view&gt;
 &lt;/forrest:views&gt;
       </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 ">&lt;forrest:css
/&gt;
+        stylesheet we use another tag within our structurer <span class="codefrag">&lt;forrest:css
/&gt;
         </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 ">&lt;forrest:css /&gt;</span> needs to be the
direct child of 
-        <span class="codefrag ">&lt;forrest:view type="html"&gt;</span>
+<span class="codefrag">&lt;forrest:css /&gt;</span> needs to be the direct
child of 
+        <span class="codefrag">&lt;forrest:view type="html"&gt;</span>
       
 </div>
 </div>
@@ -709,7 +715,7 @@
 &lt;/forrest:views&gt;
       </pre>
 <p>As a second example, let us change 
-        as well the content-main by adding another hook <span class="codefrag ">&lt;forrest:hook
name="content"/&gt;
+        as well the content-main by adding another hook <span class="codefrag">&lt;forrest:hook
name="content"/&gt;
         </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">&lt;project&gt;</span>, i.e., outside of
+      <span class="codefrag">&lt;target&gt;</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">&lt;import&gt;</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">&lt;project name="mysampleproject" default="main"&gt;
 	&lt;property name="notify.email.host" value="smtp.myhost.com"/&gt;
 	&lt;property name="notify.email.to" value="me@domain.com"/&gt;
@@ -302,148 +309,171 @@
 &lt;/project&gt;
 
 </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 ">&lt;target
-      name="main" depends="getsrc, build, deploy, notify"/&gt;</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">&lt;target
+        name="main" depends="getsrc, build, deploy, notify"/&gt;</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">&lt;import&gt;</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">&lt;project&gt;</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">&lt;property&gt;</span>
+          task given here:</p>
+<pre class="code">&lt;target name="getsrc.local"&gt;
+  &lt;property name="build.home-dir" location="${getsrc.local.root-dir}"/&gt;
+  [...]
+&lt;/target&gt;</pre>
+<p>Alternatively (and preferably), define your 'getsrc' target like
+          this:</p>
+<pre class="code">&lt;target name="getsrc" depends="getsrc.clean-workdir, getsrc.get,
getsrc.local"/&gt;</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 ">&lt;import
-      file="my-settings.xml"/&gt;</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">&lt;property
+        file="auth.properties"/&gt;</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 ">&lt;target name="getsrc"
-          depends="getsrc.clean-workdir, getsrc.svn"/&gt;</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">&lt;target name="getsrc"
+          depends="getsrc.clean-workdir, getsrc.svn"/&gt;</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 &lt;property&gt;</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">&lt;import&gt;</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">&lt;import&gt;</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.



Mime
View raw message