forrest-svn mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rgard...@apache.org
Subject svn commit: rev 65637 - in forrest/trunk/docs-author: . content/xdocs content/xdocs/howto
Date Sun, 14 Nov 2004 23:01:40 GMT
Author: rgardler
Date: Sun Nov 14 15:01:39 2004
New Revision: 65637

Added:
   forrest/trunk/docs-author/content/xdocs/howto/howto-forrest-from-maven.xml   (contents,
props changed)
Modified:
   forrest/trunk/docs-author/content/xdocs/howto/index.xml
   forrest/trunk/docs-author/content/xdocs/site.xml
   forrest/trunk/docs-author/status.xml
Log:
How To run Forrest from Maven (submitted by Ian Springer)

Added: forrest/trunk/docs-author/content/xdocs/howto/howto-forrest-from-maven.xml
==============================================================================
--- (empty file)
+++ forrest/trunk/docs-author/content/xdocs/howto/howto-forrest-from-maven.xml	Sun Nov 14
15:01:39 2004
@@ -0,0 +1,123 @@
+<?xml version="1.0"?>
+
+<!--
+  Copyright 2002-2004 The Apache Software Foundation
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+-->
+
+<!DOCTYPE howto PUBLIC "-//APACHE//DTD How-to V2.0//EN" "http://forrest.apache.org/dtd/howto-v20.dtd">
+
+<howto>
+
+ <header>
+  <title>How to run Forrest from within Maven</title>
+  <abstract>
+    This How-To describes how to run Forrest from within Maven.
+  </abstract>
+  <last-modified-content-date date="2004-11-12"/>
+ </header>
+
+  <audience title="Intended Audience">
+    <p>
+      Users who want to run Forrest from within Maven.
+    </p>
+  </audience>
+  
+  <purpose title="Purpose">
+    <p>
+      One may want to generate their project's documentation and/or website
+      using Forrest in lieu of Maven's site plugin.
+    </p>
+  </purpose>
+
+  <prerequisites title="Prerequisites">
+    <ul>
+      <li>Understand how to add goals to 
+      <a href="http://maven.apache.org/reference/user-guide.html#maven_xml">maven.xml</a>.</li>
+    </ul>
+  </prerequisites>
+
+  <steps title="Steps">
+    <p>
+      The procedure outlined below describes how to add a goal to your
+      project's maven.xml that will invoke Forrest's <code>site</code> target.
+    </p>
+
+    <section id="set-maven-home">
+      <title>Set the FORREST_HOME environment variable</title>
+      <p>
+        Make sure the FORREST_HOME environment variable points to your Forrest home directory
+        (i.e. the directory that contains <code>forrest.build.xml</code>) 
+        (e.g. C:\opt\apache-forrest-0.6\src\core)
+      </p>
+        
+      <fixme author="rdg">Under Forrest 0.7 the directories for 
+      Forrest have been restructured. Consequently, FORREST_HOME is no
+      longer set to the directory containing <code>forrest.build.xml</code>.
+      Update this document to reflect what should be done under 0.7.</fixme>
+    </section>
+
+    <section id="define-ant-environment-prop">
+      <title>Initialize an Ant environment property at the top of maven.xml</title>
+      <p>
+        Paste the following line at the top of your maven.xml:
+      </p>
+      <source>
+&lt;property environment="env" /&gt;
+      </source>
+    </section>
+
+    <section id="add-forrest-goal-to-maven-xml">
+      <title>Add forrest goal to maven.xml</title>
+      <p>
+        Paste the following goal into your project's maven.xml:
+      </p>
+      <source>
+&lt;goal name="forrest" description="runs Forrest"&gt;
+  &lt;property name="forrest.home" location="${env.FORREST_HOME}" /&gt;
+  &lt;property name="forrest.install.dir" location="${forrest.home}/../.." /&gt;
+  &lt;property name="forrest.ant.home" location="${forrest.install.dir}/tools/ant" /&gt;
+  &lt;java classname="org.apache.tools.ant.Main" fork="true" failonerror="true" maxmemory="128M"&gt;
+    &lt;classpath&gt;
+      &lt;fileset dir="${forrest.ant.home}/lib"&gt;
+        &lt;include name="*.jar" /&gt;
+      &lt;/fileset&gt;
+      &lt;pathelement path="${java.home}/../lib/tools.jar" /&gt;
+    &lt;/classpath&gt;
+    &lt;sysproperty key="ant.home" value="${forrest.ant.home}" /&gt;
+    &lt;sysproperty key="forrest.home" value="${forrest.home}" /&gt;
+    &lt;sysproperty key="basedir" value="${basedir}" /&gt;
+    &lt;sysproperty key="java.endorsed.dirs" value="${forrest.install.dir}/lib/endorsed"
/&gt;
+    &lt;arg line="-f ${forrest.home}/forrest.build.xml" /&gt;
+  &lt;/java&gt;
+&lt;/goal&gt;      
+      </source>
+      <p>
+        It is necessary to fork a separate java process because Maven 1.0 
+        embeds Ant 1.5.2, but Forrest's forrest.build.xml requires Ant 1.6. 
+        The goal makes use of the copy of Ant 1.6 that is bundled with 
+        Forrest, so it's not even necessary to have Ant 1.6 installed separately.
+      </p>
+    </section>
+  </steps>
+
+  <feedback title="Feedback">
+    <p>
+      Please provide feedback about this document via the
+      <a href="ext:mail-lists">mailing lists</a>.
+      <!-- Original author: Ian Springer (ips AT apache DOT org) -->
+    </p>
+  </feedback>
+  
+</howto>

Modified: forrest/trunk/docs-author/content/xdocs/howto/index.xml
==============================================================================
--- forrest/trunk/docs-author/content/xdocs/howto/index.xml	(original)
+++ forrest/trunk/docs-author/content/xdocs/howto/index.xml	Sun Nov 14 15:01:39 2004
@@ -54,6 +54,10 @@
           file to change the color of the corner images to be suitable for
           your own skin colors. Advanced use explains editing the *.css too.
         </li>
+        <li><link href="site:howto/maven">How to run Forrest from within Maven</link>
+        - For Maven users who want to generate their project's documentation and/or website
+          using Forrest in lieu of Maven's site plugin.
+        </li>
       </ul>
     </section>
     

Modified: forrest/trunk/docs-author/content/xdocs/site.xml
==============================================================================
--- forrest/trunk/docs-author/content/xdocs/site.xml	(original)
+++ forrest/trunk/docs-author/content/xdocs/site.xml	Sun Nov 14 15:01:39 2004
@@ -110,6 +110,7 @@
     <pdf-tab label="Create tab PDF" href="howto-pdf-tab.html"/>
     <editcss label="Edit CSS (WYSIWYG)" href="howto-editcss.html"/>
     <corner-css label="CSS corner SVG" href="howto-corner-images.html"/>
+    <maven label="Maven Integration" href="howto-forrest-from-maven.html"/>
     <buildPlugin label="Build a Plugin" href="howto-buildPlugin.html"/>
   </howto>
 

Modified: forrest/trunk/docs-author/status.xml
==============================================================================
--- forrest/trunk/docs-author/status.xml	(original)
+++ forrest/trunk/docs-author/status.xml	Sun Nov 14 15:01:39 2004
@@ -44,6 +44,10 @@
 
   <changes>
     <release version="0.7-dev" date="not yet released">
+      <action dev="RDG" type="add" context="docs" 
+        due-to="Ian P. Springer" fixes-bug="FOR-369">
+      Added <link href="site:howto/maven">How-To Run Forrest from Maven</link>

+      </action>
       <action dev="RDG" type="add" context="docs">
       Added <link href="site:howto/buildPlugin">How-To Build a plugin</link>

       </action>

Mime
View raw message