New customization guide (MPAPPGEN-20)

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

genapp/xdocs/changes.xml

@@ -25,6 +25,7 @@
   </properties>
   <body>
     <release version="2.3" date="in cvs">
+      <action dev="felipeal" type="add" issue="MPGENAPP-20" due-to="Miguel Griffa">Added customization guide.</action>
       <action dev="felipeal" type="add" issue="MPGENAPP-19" due-to="Miguel Griffa">Added Velocity-based webapp template (named <code>web-velocity</code>).</action>
     </release>
     <release version="2.2" date="2004-05-15">

genapp/xdocs/customization_guide.xml

@@ -0,0 +1,103 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!-- 
+/*
+ * Copyright 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.
+ */
+ -->
+
+<document>
+
+  <properties>
+    <title>Customization Guide</title>
+    <author email="m_griffa@yahoo.com">Miguel Griffa</author>
+  </properties>
+
+  <body>
+    <section name="Introduction">
+      <p>
+        The genapp plugin provides several general purpose templates.
+        Companies or large sites may have their own application templates
+        that for whatever reason they want to keep in-house. 
+      </p>
+      <p>
+          This guide is intended to help writing and maintaining application
+          templates outside the plugin. In this manner, the plugin can be
+          updated and the template is not affected.
+      </p>
+      <p>
+          If you have some good application templates, consider contributing a
+          general purpose version to the project, so more users can benefit
+          from it.
+      </p>
+      <subsection name="Uses">
+          <p>
+              Information on this guide can be used to write custom templates
+              or to simply customize built-in templates. Since templates are
+              currently stored in a JAR file you cannot modify that template
+              without having to maintain a customized version of the plugin
+              (for example, an upgrade of the plugin will not include you
+              changes, unless they were committed to maven's cvs).
+          </p>
+      </subsection>
+    </section>
+    <section name="Writing the template">
+        <subsection name="Setup">
+            <p>
+                Go to you local maven installation and extract in a working
+                directory the contents of
+                <code>plugins/maven-genapp-plugin.x.y.jar</code>
+                (where <code>x.y</code> is the version of the plugin).
+            </p>
+            <p>
+                Inside the plugin-resources directory you can find many
+                directories with different templates. These directories contain
+                the resources associated with the different templates. Start by
+                copying one of there to a different directory. This new copy 
+                will be the one that we'll be working on. For this example, we
+                will consider the new template directory to be on
+                <source>/opt/templates/foo</source>
+            </p>
+        </subsection>
+        <subsection name="Template customization">
+            <p>
+                Go to <code>/opt/templates/foo</code>. You should find there a
+                <code>template.properties</code> file and a 
+                <code>template-resources</code> directory. The template
+                properties file may be customized (open and play with its
+                properties).
+            </p>
+            <p>
+                Just play with files in the template until you have what you
+                want. One of the things that you are likely to change is the
+                <code>project.xml</code> file, to have you company information,
+                your directory layout and the reports you use.
+            </p>
+        </subsection>
+    </section>
+    <section name="Using">
+        <p>
+            Create a directory for your application and type
+ <source>maven genapp -Dmaven.genapp.template.dir=/opt/templates/foo</source>
+            This should generate the application template you defined.
+        </p>
+        <p>
+            If you are willing to write more templates, consider using the
+            property <code>maven.genapp.template.repository</code> and place 
+            there all your templates. Then, you can invoke you template by the
+            name of the directory.
+        </p>
+    </section>
+  </body>
+</document>

genapp/xdocs/navigation.xml

@@ -30,6 +30,7 @@
       <item name="Properties"         href="/properties.html" />
       <item name="Faqs"               href="/faq.html" />
       <item name="Templates list"     href="/templates.html" />
+      <item name="Customization guide"     href="/customization_guide.html" />
     </menu>
   </body>
 </project>