Doc fixes thanks to Paul Spencer.

git-svn-id: https://svn.apache.org/repos/asf/maven/maven-1/plugins/trunk@115885 13f79535-47bb-0310-9956-ffa450edef68

cruisecontrol/project.xml

@@ -23,7 +23,7 @@
   <id>maven-cruisecontrol-plugin</id>
   <name>Maven Cruise Control Plugin</name>
   <currentVersion>1.5-SNAPSHOT</currentVersion>
-  <description>A plugin to handle the generating and maintaining of Cruise Control configuration. Requires Maven 1.0 RC2.</description>
+  <description>A plugin to handle the generating and maintaining of Cruise Control configuration. Requires Maven 1.0.</description>
   <shortDescription>Cruise Control Plugin for Maven</shortDescription>
   <url>http://maven.apache.org/reference/plugins/cruisecontrol/</url>
   <issueTrackingUrl>http://jira.codehaus.org/browse/MPCRUISECONTROL</issueTrackingUrl>

cruisecontrol/xdocs/faq.fml

@@ -84,6 +84,61 @@ maven.cruisecontrol.template=${plugin.resources}/my-cc-template.jsl]]></source>
       </answer>
     </faq>
 
+    <faq id="setup">
+      <question>
+        How do I setup my project to be built using Cruise Control?
+      </question>
+      <answer>
+        <ul>
+          <li>Install Cruise Control.  Preferably on a different machine.</li>
+          <li>
+            Checkout the project into the 
+            <code>${maven.cruisecontrol.checkout.dir}</code>.  The checkout 
+            should be done as the same user defined in project.xml.  This is 
+            because the SCM plugin <strong>must</strong> be able to keep the
+            project in sync with the repository.
+          </li>
+          <li>
+            Using Maven and the cruisecontrol plugin, update the CruiseControl
+            configuration file.
+          </li>
+          <li>Restart CruiseControl</li>
+        </ul>
+      </answer>
+    </faq>
+
+    <faq id="whenToRebuild">
+      <question>
+        How often should I update the CruiseControl configuration file?
+      </question>
+      <answer>
+        Since there is limited information in the file, not very often.  You
+        should regenerate the file when:
+        <ul>
+          <li>Source repository configuration changes</li>
+          <li>Developer email address changes</li>
+          <li>Directories on used by Cruise Control change, i.e. the logs
+              directory
+          </li>
+          <li>Project goals change</li>
+          <li>List of dependent project change</li>
+        </ul>
+      </answer>
+    </faq>
+
+    <faq id="editConfigFile">
+      <question>
+        Do I need to edit the CruiseControl configuration file?
+      </question>
+        By default no, since much of the information in the file originates
+        in properties and project.xml.  For changes that affect the generation
+        of the project or projects, you may want to create you own template. 
+        If you have dependencies defined, then you need to ensure the order 
+        of the projects in the file corresponds with the order the project
+        should be built.
+      <answer>
+      </answer>
+    </faq>
 
   </part>
 

cruisecontrol/xdocs/properties.xml

@@ -35,6 +35,10 @@
           <td>No</td>
           <td>
             <p>Location of cruise control installation - for finding the reporting directory</p>
+            <p>
+        <strong>NOTE: </strong>It may be more appropriate to set this in build.properties
+        on the CruiseControl server since the value may differ from developer to developer.
+            </p>
           </td>
         </tr>
         <tr>
@@ -51,6 +55,10 @@
           <td>
             <p>Default value is
               <code>localhost</code>.</p>
+            <p>
+        <strong>NOTE: </strong>It may be more appropriate to set this in build.properties
+        on the CruiseControl server since the value may differ from developer to developer.
+            </p>
           </td>
         </tr>
         <tr>
@@ -67,6 +75,10 @@
           <td>
             <p>Where to checkout/update code temporarily. Default value is
               <code>${basedir}/checkout</code>.</p>
+            <p>
+        <strong>NOTE: </strong>It may be more appropriate to set this in build.properties
+        on the CruiseControl server since the value may differ from developer to developer.
+            </p>
           </td>
         </tr>
         <tr>
@@ -75,6 +87,10 @@
           <td>
             <p>Default value is
               <code>${maven.build.dir}/cc-logs</code>.</p>
+            <p>
+        <strong>NOTE: </strong>It may be more appropriate to set this in build.properties
+        on the CruiseControl server since the value may differ from developer to developer.
+            </p>
           </td>
         </tr>
         <tr>
@@ -91,6 +107,10 @@
           <td>
             <p>Config file to update/create. Default value is
               <code>${basedir}/cruisecontrol.xml</code>.</p>
+            <p>
+        <strong>NOTE: </strong>It may be more appropriate to set this in build.properties
+        on the CruiseControl server since the value may differ from developer to developer.
+            </p>
           </td>
         </tr>
         <tr>
@@ -106,6 +126,10 @@
           <td>Yes</td>
           <td>
             <p>Template file to use in generating the cruisecontrol.xml file.</p>
+            <p>
+        <strong>NOTE: </strong>It may be more appropriate to set this in build.properties
+        on the CruiseControl server since the value may differ from developer to developer.
+            </p>
           </td>
         </tr>     
         <tr>
@@ -113,10 +137,16 @@
           <td>Yes</td>
           <td>
             <p>
-				List of projects that should trigger this project to build when 
+				A comma separated list of projects that should trigger this project to build when 
 				they are built.  Allows you to build a project whose dependencies
 				have changed.
-			</p>
+            </p>
+            <p>
+        <strong>NOTE: </strong>You may need to edit the config file to ensure that dependent
+        project appear prior to the project.  This is because CruiseControl builds projects in
+        the order that appear in the config file.  Failure to order the project properly may 
+        results in continuious rebuilding of project and/or avoidable build failures.
+            </p>
           </td>
         </tr> 		
         <tr>
@@ -125,9 +155,26 @@
           <td>
             <p>
 				The root of the cruisecontrol site used in generating the link to
-				CruiseControl.  By default this is <code>pom.url</code>.  While not required,
+				CruiseControl.  By default this is 
+        <code>${pom.url}/cruisecontrol</code>.  While not required,
 				typically you will need to set this.
-			</p>
+            </p>
+          </td>
+        </tr> 		   
+        <tr>
+          <td>maven.cruisecontrol.buildresults.url</td>
+          <td>Yes</td>
+          <td>
+            <p>
+				The url of the cruisecontrol site used in generating the link to
+				CruiseControl.  By default this is 
+        <code>${maven.cruisecontrol.site}/buildresults/${pom.artifactId}</code>.  
+            </p>
+            <p>
+        <strong>Note: </strong>Since the cruisecontrol report is not one of the
+        defaults reports, you must add the cruisecontrol report to see a
+        link to the Cruise Control Build Results under Project Reports.  
+            </p>
           </td>
         </tr> 		   
       </table>